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PREFACE 



This manual describes the RL51 linker and locator and the LIB51 librarian for 
program modules produced by MCS-51 language translators such as ASM51 and 
PL/M-51. 

The RL51 and the LIB51 program operate on an Intel development system with an 
8080 or 8085 processor. The configuration must include 64K of RAM, a console, and 
at least one diskette or hard disk drive running under the ISIS-II operating 
environment. 

NOTE 

In this manual, the term MCS-51 refers to all members of the MCS-51 family 
of microcomputers and to the software development tools for the MCS-5 1 
family. 

Reader's Guide 

The manual is organized into six chapters and five appendixes: 

Chapter 1 discusses the advantages of modular programming and summarizes the 
process of modular programming with the MCS-51 development tools. 

Chapter 2 reviews the mechanics of linkage and location for the RL5 1 program. 

Chapter 3 gives the details on invoking the linker/locator. 

Chapter 4 discusses the files and displays produced by the RL51 program, with 
examples. 

Chapter 5 contains three examples of programs, with the link and locate steps for 
each program. 

Chapter 6 describes the LIB51, the MCS-51 library manager and its usage. 

Appendix A presents the syntax of the RL51 commands with brief definitions of the 
controls. 

Appendix B Usts the error messages and warnings displayed by RL51, with suggestions 
for corrective action. 

Appendix C lists a summary of LIB51 commands. 

Appendix D lists the error messages generated by LIB51, with suggestions for 
corrective action. 

Appendix E contains hexadecimal-decimal conversion tables as a convenient reference. 

Related Literature 

To help you use this manual, you should be familiar with the contents of the follow- 
ing manuals: 

® MCS-51 Macro Assembler User's Guide, order number 9800937 
• PL/M-51 JJsefs Guide, order number 121966 
® MCS-51 Family of Single-Chip Microcomputers User's Manual, order number 

121517 
^ ISlS-ll User's Guide, order number 9800306 
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The following manuals may also be of interest: 

® MCS-51 Macro Assembly Language Pocket Reference, order number 9800935 

® MCS-51 Utilities Pocket Reference, order number 121817 

® ICE-51 In-Circuit Emulator Operating Instructions for ISIS-II Users, order 
number 9801004 



Notational Conventions 

UPPERCASE 



Characters shown in uppercase must be entered in the order 
shown. Enter the command words as shown, or use a system- 
defined abbreviation. You may enter the characters in upper- 
case or lowercase. 



italic 



directory-name 



Italic indicates a meta symbol that may be replaced with an 
item that fulfills the rules for that symbol. The actual symbol 
may be any of the following: 

Is that portion of a patfiname that acts as a file locator by 
identifying the device and/or directory containing the 
filename. 



filename 
system-id 

Vx.y 

[ ] 
i } 



Is a valid name for the part of a pathname that names a file. 

Is a generic label placed on sample listings where an oper- 
ating system-dependent name would actually be printed. 

Is a generic label placed on sample listings where the version 
number of the product that produced the listing would 
actually be printed. 

Brackets indicate optional arguments or parameters. 

One and only one of the enclosed entries must be selected 
unless the field is also surrounded by brackets, in which case 
it is optional. 

At least one of the enclosed items must be selected unless the 
field is also surrounded by brackets, in which case it is 
optional. The items may be used in any order unless other- 
wise noted. 



[..-.] 



punctuation 



The vertical bar separates options within brackets [ ] or 
braces i > . 

Ellipses indicate that the preceding argument or parameter 
may be repeated. 

The preceding item may be repeated, but each repetition must 
be separated by a comma. 

Punctuation other than ellipses, braces, and brackets must be 
entered as shown. For example, the punctuation shown in the 
following command must be entered: 

SUBMIT PLM86CPR0GA , SRC , ^9 SEPT 8K) 
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In interactive examples, user input lines are printed in white 
on black to differentiate them from system output. 



icr > 



Indicates a carriage return. 
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CHAPTER 1 
INTRODUCTION 



The Adwantages of Modular Programming 

Many programs are too long or complex to write as a single unit. Programming 
becomes much simpler when the code is divided into small functional units. Modular 
programs are usually easier to code, debug, and change than monolithic programs. 

The modular approach to programming is similar to the design of hardware that 
contains numerous circuits. The device or program is logically divided into "black 
boxes" with specific inputs and outputs. Once the interfaces between the units have 
been defined, detailed design of each unit can proceed separately. 



Efficient Program Development 

Programs can be developed more quickly with the modular approach because small 
subprograms are easier to understand, design, and test than large programs. With the 
module inputs and outputs defined, the programmer can supply the needed input and 
verify the correctness of the module by examining the output. The separate modules 
are then linked and located into one program module. Finally, the completed program 
is tested. 



Multiple Use of Subprograms 

Code written for one program is often useful in others. Modular programming allows 
these sections to be saved for future use. Because the code is relocatable, saved modules 
can be linked to any program that fulfills their input and output requirements. With 
monolithic programming, such sections of code are buried inside the program and are 
not so available for use by other programs. 

If you put your frequently-used subprograms into a library, RL5 1 will take care to 
load only those you need. Thus, you can save RAM and ROM without having to 
keep track of what is needed and what is not. 



Ease of Debugging and Modifying 

Modular programs are generally easier to debug than monolithic programs. Because 
the modular interfaces are well-defined, problems can be isolated to specific modules. 
Once the faulty module has been identified, fixing the problem is considerably simpler. 
When a program must be modified, modular programming simplifies the job. You 
can link new or modified modules to the existing program with confidence that the 
rest of the program will not be changed. 



MCS®-51 Modular Program Deweiopment Process 

This section is a brief review of the program development process using an MCS-51 
language translator (e.g., the relocatable MCS-51 assembler or PL/M-51 compiler), 
linker/locator, code converter programs, PROM programmer, and ICE™-51 in-circuit 
emulator. The process is shown in figure 1-1. 
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Segments, Modules, Libraries, and Programs 

In the initial design stages, the tasks to be performed by the program are defined and 
then partitioned into subprograms. Here are brief introductions to the kinds of 
subprograms used with the MCS-51 assembler and linker/locator. 

A segment is a unit of code or data memory. A segment may be relocatable or 
absolute. A relocatable segment in a module can be a complete segment or can be a 
"partial" segment to be combined with other partial segments from other modules. 
A relocatable segment has a name, type, and other attributes that allow the linker to 
combine it with other partial segments, if required, and to correctly locate the segment. 
An absolute segment has no name and cannot be combined with other segments. See 
Chapter 2 for more detail on partial segments. 

A module contains one or more segments or partial segments. A module has a name 
assigned by the user. The module definitions determine the scope of local symbols. 
An object file contains one or more modules. You can add modules to a file by trans- 
fering the new modules from their individual files to another file (e.g., COPY f//el, 
file! TO ^/e3). 

A library is a file that contains one or more modules. A library file is internally 
marked as a library, so RL5 1 can easily identify it as such. RL5 1 selects, out of the ' 
modules in the library, only those previously referenced. Libraries are created using 
the LIB51 utility, which is described in detail in Chapter 6. 

A program consists of a single absolute module, merging all absolute and relocatable 
segments from all input modules. The name of the output module produced by RL5 1 
can be defined by the user or allowed to default to the name of the first input module. 
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Entering and Editing Source Modules 

After the design is completed, use the text editor on your system to code the modules 
into source files. The source modules are coded in assembly language or a high-level 
language such as PL/M-5L The editor may also be used to make corrections in the 
source code. 



Assembly and Compilation 

The assembler (ASM51) and compiler (PL/M-51) translate the source code into 
relocatable object code, producing an object file. The ASM51 object file is relocata- 
ble when at least one input segment is relocatable; otherwise the object file is an 
absolute file. The PL/M-51 object file is always relocatable. The assembler and 
compiler also produce a listing file showing the results of the translation. When the 
ASM51 or PL/M-51 invocation contains the DEBUG control, the object file also 
receives the symbol table and other debug information for use in symbolic debugging 
of the program. 



Relocation and Linkage 

After translation of all modules of the program, the linker/locator, RL51, processes 
the object module files. The RL51 program combines relocatable partial segments 
with the same name, then assigns absolute memory locations to all the relocatable 
segments. RL51 also resolves all references between modules, using the library files 
when they are necessary for this resolution. RL51 outputs an absolute object module 
file that contains the completed program, and a summary listing file showing the 
results of the link/locate process, including a memory map, symbol table, and, 
optionally, an inter-module cross-reference (IXREF) listing. 



ROM and PROM Versions 

The absolute object module produced by RL5 1 can be loaded into members of the 
MCS-51 family of microcomputers. For ROM versions of the microcomputer, the 
program is masked into ROM during the manufacturing process. For PROM versions 
and versions with no on-chip CODE memory, a PROM programmer is used to load 
the absolute module into program memory accessible to the microcomputer for 
execution. Refer to the MCS-51 Family of Single Chip Microcomputers User's 
Manual for details on the versions of microcomputers available. 



ICE'^-^51 In-Circuit Emulator 

The ICE-51 in-circuit emulator is used for software and hardware debugging and 
integration into the final product. The absolute object modules produced by RL51 
can be loaded into the emulator's memory for execution. Refer to the ICE-51 manual 
listed in the preface for details. 



SDK-51 System Design Kit 

The SDK-51 system design kit for MCS-51 microcomputers is a useful tool for evalu- 
ation and simple program execution. However, the SDK-51 requires the hexadecimal 
object code format output by previous assemblers. For use with the SDK-51, the 
absolute object file must be processed by the OBJHEX code conversion program. 
Refer to the ISIS-II Users Guide for details on OBJHEX. 
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Keeping Track of Files 

It is convenient to use the extensions of filenames to indicate the stage in the process 
represented by the contents of each file. Thus, source code files can use extensions 
like .SRC, .A51, or .P51 (indicating that the code is for input to ASM51 or 
PL/M-51). Object code files receive the extension .OBJ by default or the user can 
specify another extension. Executable files generally have no extension. Listing files 
can use .LST, the default extension given by the translator. RL51 uses .M51 for the 
default listing file extension (in order not to destroy the ASM51 listing file with the 
.LST extension). 

Library files customarily have the extension .LIB. 

Use caution with the extension .TMP, as many ISIS-II utilities (including RL51 and 
LIB51) create temporary files with this extension. These utilities will delete your file 
if it has the same name and extension as the temporary files they create. 
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CHAPTER 2 

THE MECHANICS OF LINKAGE 

AND LOCATION WITH RL51 



This chapter describes the operation of the RL5 1 program. Most of the process is 
transparent to the user; however, an understanding of the operation at the level 
presented here will help you to use the linking and locating controls in the RL51 
invocation. More specific details on the allocating process appear in Chapter 3. 



Major Functions 

The RL51 program performs the following major functions: 

1. Selects modules (including library processing) 

2. Combines relocatable partial segments of the same name into a single segment 

3. Allocates memory for the combined segments resulting from the previous step, 
and for all other complete relocatable segments from the input modules 

4. Overlays data segments 

5. Resolves external symbol references between the input modules 

6. Binds relocatable addresses to absolute addresses 

7. Produces an absolute object file 

8. Produces a listing file consisting of a link summary, a symbol table, and an IXREF 
report 

9. Detects and lists errors found in the input modules or in the RL51 command 
invocation 

Functions 1, 2, 3, 5, and 6 are described in the remainder of this chapter. Functions 
7, 8, and 9 are discussed in Chapter 4; the RL51 command invocation and overlaying 
of data segments are described in Chapter 3. 



Selecting Modules 

Input files are processed in the order they are specified in the invocation command. 

The processing of an input file varies according to the content — that is, whether it is 
a library or non-library file. A non-library file may contain a concatenation of zero 
or more object modules. A library file contains zero or more object modules together 
with control information. A module in a non-library file is processed if it was explic- 
itly listed in the module list, or if the module list was not specified at all (in other 
words, as if all modules were listed implicitly). 

The processing of a library file is more complicated. If a module list was specified 
for the library file, then it is processed in the same manner as a non-library file. If a 
module list was not specified, then the library file is processed only if the previously 
processed modules contained at least one unresolved external. The library is scanned 
for modules containing public symbols that match as yet unresolved externals. Each 
such module is processed as if it were explicitly specified. The selection process 
continues until the modules in the library cannot satisfy any unresolved externals 
(including any externals encountered while processing modules from the library). 

RL5 1 will report an error if the same module name is encountered more than once 
during the link process. 
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Take TRIGON.LIB as an (utterly fictitious) example. Assume it contains procedures 
called SINE, COSINE, TANGENT, ARCSINE, ARCCOS, ARCTAN, HYPER- 
BOLIC_SINE, and HYPERBOLIC_COSINE. 

When RL51 starts processing TRIGON.LIB, it has already made a first pass over 
all files that appear before it in the invocation line. If one of these contains a refer- 
ence to the external SINE, and there is no public by that name, RL5 1 v^ill assume 
that the procedure SINE from TRIGON.LIB is to be loaded. Otherv^ise, it will leave 
SINE alone for the moment. 

If, while loading from TRIGON.LIB, RL51 encounters new externals that a module 
in the library can resolve, it will scan the library once more. Thus, there is no logical 
order among modules in a library; they are all equal. If TANGENT calls SINE and 
COSINE, and they are in the same library, in any order whatsoever, a reference to 
TANGENT will cause all three to be loaded. 



Partial Segments 

A segment is a unit of code memory or data memory. The portion of a segment 
defined in one module is called a partial segment. A partial segment has the following 
attributes (defined in the source module): 

® Name. A relocatable segment has a name by which it is linked with other portions 
of the same segment from other modules. Absolute segments do not have names. 

® Type. The type identifies the address space to which a segment belongs: CODE, 
XDATA, DATA, IDATA, or BIT. 

® Relocatability. For relocatable segments only, this attribute describes any special 
constraints on relocation (PAGE, INPAGE, BLOCK, BITADDRESSABLE, or 
UNIT). 

® Size. The size of the segment in bytes or bits, depending on the type. 

® Base Address. The lowest address in the partial segment. For absolute segments, 
the base address is assigned at assembly time; for relocatable segments, it is 
assigned at location time. 

Absolute segments are complete segments; they are taken as is into the output module. 
Relocatable segments are either defined by ASM51 users (using the SEGMENT 
directive in the source module) or automatically generated by the PL/M-51 compiler. 

Refer to the MCS~51 Macro Assembler User's Guide for details on the assembler 
directives. 



Combining Relocatable Segments 

After processing the invocation command, RL5 1 performs a first pass over the input 
modules identified in the command. Pass 1 generates a segment table, a publics ta^ble, 
and an unresolved externals table. The segment table is discussed in this section; the 
other two tables are discussed later in this chapter. 

The segment table contains the name, length, type, and relocation attribute of all 
combined segments from all modules. Combined segments are produced from the 
partial segments in the input modules according to the following rules: 

® RL51 combines all partial segments with the same name into one relocatable 
segment. For example, if three input modules each have a partial relocatable 
segment named STACK, the segment table will have one segment named STACK 
that combines the length of the three partial segments. 
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All the partial segments to be combined must be of the same type (CODE, DATA, 
IDATA, XDATA, or BIT). If any partial segments have the same names but 
different types, an error occurs. 

The length of the combined segment must not exceed the physical size of the 
memory type. Details on maximum size appear later in this chapter. 

The relocation attributes of all the partial segments to be combined must either 
be the same or UNIT-aligned combined with one other attribute. The combined 
segment receives the relocation attribute shared by the input partial segments, 
or, if the segments have attribute UNIT-aligned combined with one other attrib- 
ute, the combined segment receives the more restrictive attribute. 

For example, if the three partial segments named STACK have relocation attri- 
butes UNIT, PAGE, and UNIT, the combined segment has attribute PAGE 
(i.e., page-aligned). Note that the relocation attribute is applied to the combined 
segment, not to each component segment. To continue the example, since the 
relocation is PAGE, the combined segment will start on a page boundary, but 
the component segments will be packed together without any gaps. 



Allocating Memory for Segments 

After the segment table is complete, RL5 1 can locate the segments within the memory 
spaces. Table 2-1 shows the address spaces used by MCS-51 processors, and the 
corresponding segment types. 

The allocation process has a definite sequence; the exact order is presented in 
Chapter 3. As an overview, the process follows a general pattern of rules as follows: 

1. Each of the types of memory space is allocated independent of the other spaces. 

2. Within each space, absolute segments are allocated first, then segments specified 
within locating controls in the RL5 1 command, then other relocatable segments. 

3. Because the on-chip data space represents three overlapping address spaces 
(DATA, IDATA, AND BIT), the general pattern in rule 2 is modified. 

a. Absolute BIT, DATA, and IDATA segments, and register banks are allocated 
first. 

b. Segments specified in PRECEDE and BIT controls are allocated next, then 
other relocatable BIT (and BIT-ADDRESSABLE) segments (following 
rule 2). 

c. DATA type segments are allocated next: segments in the DATA control first, 
then other relocatable DATA segments. 

d. IDATA type segments (except 7STACK) are allocated next; segments in the 
IDATA control first, then other relocatable IDATA segments. 

e. Segments specified in the STACK control are allocated, at as low an address 
as possible, provided that it is above all BIT, DATA, and IDATA segments 
allocated under (c) and (d). 

f. Last, the segment ? STACK, if it exists and is IDATA, and is not mentioned 
in an explicit location control, is now allocated, at as low an address as possi- 
ble, provided that it is above all BIT, DATA, and IDATA segments allocated 
under (c) and (d) and (e). 

In most cases, you do not need to use any explicit controls to obtain a satisfactory 
allocation of segments. RL5 1 tries to fit your segments into the designated memory 
spaces as best it can following the rules. As you can see, most of the complexity 
occurs in the on-chip data space. 
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Table 2-1 . Address Spaces and Segment Types 



Memory Space 


Maximum Size 


Addresses 


Segment Type 


Code 


64K bytes 


OOOOH - OFFFFH 


CODE 


External data 


64K bytes 


OOOOH - OFFFFH 


XDATA 


On-chip data 
(direct addressing) 


128 bytes 


OOH - 7FH 


DATA 


On-chip data 
(indirect addressing) 


256 bytes 
(see 1) 


OOH - OFFH 


IDATA 


Bit space in 
on-chip data 
memory 


128 bits 
(see 2) 


OOH - 7FH 


BIT 



1 . The amount of indirectly addressable on-chip data memory is machine-dependent within the 
MCS-51 microcomputer family (see the discussion of RAMSIZE control in Chapter 3). 

2. This bit space overlaps byte addresses 20H - 2FH in on-chip data memory. 

Note: Addresses in the special function register memory (direct data addresses 80H - OFFH, bit 
addresses 80H - OFFH) cannot be relocated; they are always absolute. Thus, these addresses 
are not referenced in this table. 



Rule (f) applies to PL/M-5L PL/M-51 produces for the stack an IDATA segment 
called 7STACK, whose size is 1. Although, by applying rule (f), RL51 makes the 
stack as big as possible, it is the user responsibility to ensure that the size of the stack 
is large enough (the segment map shows where the stack' is located). 



No rules for the allocation process can guarantee an optimal solution. If you are short 
of memory and RL5 1 's first try is not satisfactory, you can place the segments in 
memory using the locating controls. Details on the locating controls are given in 
Chapter 3. 



Overlaying Data Segments 

On-chip RAM is a scarce resource on the MCS-51. To economize, the PL/M-51 
compiler overlays data segments in the compiled module. RL-51 completes the work 
by overlaying the data segments across modules. This is accomplished by using the 
OVERLAY control. If RL-51 informed you about ignored segments due to lack of 
on-chip RAM, try this control. The use of OVERLAY is, in general, straightforward. 
However, for complex applications (for example, those with mixed ASM-51 and 
PL/M-51 modules), consult Chapter 3. 



Resolving External References 

An external reference points to a location in another module. The EXTERNAL 
declaration for symbols tells RL5 1 that the reference is to a location defined in another 
module. In the latter module, the symbol is declared PUBLIC so that external refer- 
ences to that symbol in other modules can be satisfied. 

As it processes the input modules, RL51 builds a table of public symbols and 
unresolved external references. As each public symbol is added to the table, any 
external references to that symbol are deleted. After all segments have been located, 
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the public symbols are bound to absolute addresses. RL51 issues a warning for any 
unresolved externals that remain in the table. 

External symbols and corresponding public symbols must be compatible. That is, both 
must be defined to address the same address space, or at least one must be defined 
as a typeless symbol (NUMBER); and if the symbol represents a PL/M-51 proce- 
dure name, then both must share the same register bank (i.e., must be declared within 
the PL/M-51 source modules with the same USING attribute). 



Binding Relocatable Addresses 

After allocating memory for the combined segments and binding the public symbols, 
RL51 makes a second pass (pass 2) through the input modules to build the listing 
file and fixup (i.e., bind to absolute addresses) any relocatable or external references. 
At this point, RL51 also processes debug records if requested, and performs fixups to 
any relocatable debug symbols that require processing to compute their absolute 
addresses. 
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CHAPTER 3 
USING THE RL51 PROGRAM 



Introduction 

The RL51 program performs two functions for MCS-51 programs: 

® The link function, combining a number of object modules specified in an input 
list into a single object module in an output file 

• The locate function, assigning absolute addresses to any relocatable addresses in 
the input modules 

This chapter explains how to enter commands, how to continue a long command onto 
more than one input line, how to enter comments in the invocation, and how to use 
abbreviations of the command words. 

The chapter then presents a summary of the format of the RL5 1 invocation command, 
followed by details on the elements of the command with examples. 

Command Entry, Continuation Lines, and Comments 

The RL51 command is a standard ISIS-II file invocation. Terminate the command 
with the RETURN key. Note that the terminating carriage return is not shown in 
the command format notation. 

Because of the many options available with the RL5 1 command, command lines can 
become very long. To break a command into several input lines, use the continuation 
character, an ampersand (&), before the RETURN to end intermediate lines of the 
command. 

You can break a command between command words or other entries, but not in the 
middle of a word or parameter. The program begins a continuation line with a double 
asterisk ('^*) as a prompt. 

The continuation feature is not shown in the format notation, but examples of contin- 
ued commands occur in the discussions of command elements. 

Any characters in a line following a semicolon character (;) or an ampersand are 
treated as a comment. 



RL51 Command Format Summary 

Here is a summary of the syntax of the RL51 invocation command. Refer to the 
Preface for an explanation of the command format notation. 

The RL51 command has the overall format: 

[ s Fn s ] R L 5 1 input-list I T output-file 1 I control-list 1 



where 

input-list 



is a list of filenames separated by commas. The files named 
in /npiif-//sf should contain the relocatable modules to be linked 
and located in the final absolute output module. For each 
file, you can additionally specify which modules are to be 
included. 
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output-file is the name of the file that is to receive the output module. If 

you omit this entry, the program will supply a default name 
based on the first filename in the input list. 

control-list selects options for listing, linking, and locating the output. 

The listing controls specify what information is to be sent to 
the listing file, and the page width to be used. The linking 
controls specify the name of the output module, and deter- 
mine what debug information is to be placed in the output 
file. The locating controls allow you to assign absolute 
addresses to relocatable segments, and to specify the order of 
relocatable segments within a given type of memory. The 
configuration control is used to describe the actual configu- 
ration the object is aimed to. The overlay control overlays 
data segments between modules. 

The next several sections give details and examples of the elements of the RL51 
command. Table 3-1 gives brief definitions of some of the terms used in the controls. 
A list of abbreviations for command words appears at the end of the chapter. 



Table 3-1 . Definitions of Common Terms 



Term 


Definition 


name 


Names can be from 1 to 40 characters in length and must be 
composed of letters A - Z, digits - 9, or special characters (?, @, 
_). The first character must be a letter or a special character. 


module-name 


Same as name. 


segment-name 


Same as name. 


pathname 


A valid ISIS-II filename reference or device reference. See next 
two items for examples. 


filename 


A reference to a disk file. The format is 




l:F n:]root[.ext] 




Examples: PR0G1, :F1:SAMPL1, TEST.HEX, 




:F2:SAMPLE.0BJ 


device 


A reference to a non-disk device. 
Examples: :LP:, :C0:, :T0: 


value 


A 16-bit unsigned integer. 




Examples: 1011B, 304Q, 4096D (or just 4096), 0C300H 


address 


Same as value. 



Input List 

The input list tells RL5 1 what files are to be processed. The files must be disk files 
containing relocatable object modules as described in Chapter 2. 

The entry for each file in the list can include the following information: 

® The drive number. If the drive number is omitted, drive is assumed as the 
default. 

® The filename. The filename is the name of the object file including an extension 
if one exists. 

® A list of modules enclosed in parentheses. If a module list is provided, only the 
modules in the list are linked into the output file, and modules not in the list are 
ignored. If no module list is provided, the default for a non-library file is to link 
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all modules in the file into the output module. The default for a library file is to 
link only those modules that satisfy previously declared external symbols (see the 
exact process in Chapter 2 under "Selecting Modules"). 

If a module named in the module list is not present in the file, the system issues an 
error message but does not halt the link process. 

Module names (specified explicitly or implicitly) must be unique throughout the entire 
application. 



Examples 

RL51 sFlsPROG.OBJ TO sFliPROG.ABS 

In this example, the input list has one file (PROG.OBJ on drive 1); RL51 links all 
the modules in this file into the output file (PROG.ABS). (This and other examples 
omit the drive number on the RL51 reference for clarity; i.e., the examples assume 
drive 0.) 

RL51 s F 1 ; SAMP 1 , OBJ , s F 1 i S A M P 2 , B J , ; F 1 ; S A M P 3 , B J 4 
"TO ; F2 : SAMP . ABS 

In this example, the input list has three files. RL5 1 links all the modules in each of 
these files into the output file. (Note that the ** in the second line of the example is 
generated by the system in response to the continuation character & on the first line 
of the example). 

RLB1 : F1 : PR0G1 . OBJ CM0D1, M0D3), : F 1 : P R G 2 . B J CM0D2) 4 
^*T0 : F1 : PR0G3 . ABS 

Here, the input list has two input files (PROGl.OBJ and PR0G2.0BJ). From 
PROGl.OBJ, only the modules named MODI and MOD3 are to be linked into the 
output file; any other modules in file PROGl.OBJ are ignored by RL51. From 
PR0G2.0BJ, only the module named M0D2 is to be linked. 

RL51 :F1:PLHPRG,0BJ, ;F1;UTILS1.LIB, sF1:I051.LIB, PLM51.LIB 

The example introduces a typical linking using libraries. Here, PLMPRG is linked 
with two private libraries and with the mandatory library PLM51.LIB (which must 
be used if modules generated by PLM51 participate in the linkage). 

RLS1 : F1 : EXAMPL . OBJ, COTRIG.LIB, TRIG. LIB, COTRIG.LIB 

Interaction between libraries (i.e., libraries that reference each other) may sometimes 
require the same library to be mentioned twice in the input list. 

In the preceding example, COTRIG.LIB contains the COTANGENT and COSINE 
trigonometric functions, TRIG. LIB contains the SINE and TANGENT function, 
and EXAMPL.OBJ references the COTANGENT function. 

Since COTANGENT =• 1 /TANGENT, TRIG.LIB must be specified in order to 
resolve the reference to the TANGENT function. Also, since TANGENT = SINE/ 
COSINE, COTRIG.LIB must be respecified in order to resolve the reference to the 
COSINE function. 
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Output File 

The output filename is the name of the disk file that is to receive the absolute object 
module. 

If the output file name is omitted, RL5 1 creates a filename for the output file by 
removing the extension from the first filename in the input list and using the drive 
and root name only. If this input file contains no extension, a fatal error occurs. For 
example, the command: 

RLS1 PR0G1 

is illegal since the output filename defaults to PROGl. 

If there is already a file on the target drive with the name of the output file, that file 
is overwritten by the new output file. 



Examples 

RL5 1 s F 1 s PROG, OBJ TO ; F 1 s PROG 

This example specifies file PROG on drive 1 as the output file. 

RLE 1 ; F 1 5 PROG . OBJ 

This example uses the default output file generated by RL5 1 . The effect is the same 
as the first example; the output file becomes :Fl:PROG. 

RL51 : F1 : SAMPLE1 . DBJ, : F 1 : S A MP L E 2 . Q B J TO : F 2 : S AMP L . A BS 

In this example, the output file is on a different drive from the input files, and both 
the filename SAMPL and the extension .ABS are specified. 



Controls 

After the output filename, you can add a list of controls to select options for listing, 
linking, and locating the output. Use blanks (not commas) to separate controls in the 
Hst. The same control may not appear more than once in the list; if a duplicate control 
is encountered, a fatal error results and the program aborts. The next several sections 
explain the controls and give examples. 



Listing Controls 

The listing file output by RL51 can contain a link summary, a symbol table, an 
IXREF report, and a list of error messages. The link summary can contain a memory 
map of the linked segments. 

The listing controls are the PRINT option, the PAGEWIDTH control, the MAP 
option, the SYMBOLS option, the PUBLICS option, the LINES option, and the 
IXREF option. These controls allow you to specify the file or device to receive the 
output listing, to omit the listing file altogether, to omit the map from the link 
summary, or to omit local symbols, public symbols, or line numbers from the symbol 
table. You may also specify if you wish to have the IXREF report generated, and the 
specific page width to be used. 
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NOTE 

The information in the listing file is taken from the input object modules. If 
these are generated without the DEBUG option, the SYMBOLS, PUBLICS, 
and LINES information will not be available for listing. 



PRINT/NOPRINT 

The print options control the destination of the list file. 

To direct the list file to a disk file, the print control format is 

PRINT it i¥ni ] filenamei . extl } 

Example 

RL51 s F 1 s SAMPLE 1 . OBJ 4 
^^PRI NT C ; F 1 s SAMPLE , LST) 

To direct the list file to a device other than a disk file, the print control format is 

PRINT itdevicei) 

where 

device is an ISIS-II device code. Common devices are CO (console), 

LP (line printer), TO (terminal other than console), and VO 
(video terminal screen). 

If you omit the print control, or if you enter the command word PRINT without 
a filename or device name, RL5 1 creates a disk file for the listing. The name of 
the default listing file has the same root as the output filename and has an exten- 
sion of M51; the drive number is also the one used in the output filename. 

Example 

RL51 ?F1sPR0G.0BJ, sF1sPR001.0BJ TO sF2sPR002,ABS 

Since this command does not specify a listing file destination, the system creates a 
default file named PROG2.M51 on drive 2. 

The output listing filename may not be the same as the output filename or any of the 
filenames in the input list. If the listing file duplicates an input or output filename, a 
fatal error results. If the listing filename already exists on the target drive, the old 
file with that name is overwritten by the new listing file. 

The NOPRINT option specifies that no output listing file is to be produced. 
NOPRINT overrides the MAP, SYMBOLS, PUBLICS, LINES and IXREF 
controls. 



PAGEWIDTH 

The PAGEWIDTH control specifies the maximum number of columns per line in 
the print output file. The control takes the form 
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PAGEWIDTHCw/Gff/?) 
where 



is an unsigned number which specifies the maximum page 
width to be used. 

The allowable range for width is 72 to 132. The default 
PAGEWIDTH is 78. 



Listing Switches 

The MAP, SYMBOLS, PUBLICS, LINES and IXREF controls select what portions 
of the listing files are to be generated. The default of any switch (with the exception 
of IXREF) is the positive form (MAP, SYMBOLS, PUBLICS, and LINES). Table 
3-2 summarizes the listing switches. 



IXREF/NOIXREF 

This control specifies whether or not to produce the inter-module cross reference 
report. If IXREF is specified, the report is appended to the print file. 

A selection list may be added to the positive form (only) of the IXREF control. A 
selection list causes RL5 1 to output or suppress output of various selected entries to 
the IXREF report. An entry consists of a symbol and a module where this symbol is 
referenced (either as public or as external). The general form of the IXREF control 
is 



IXREF EC selection-item i , 



] ) ] 



where 

selection-item is either (NO)GENERATED or (NO)LIBRARIES. If 

IXREF is specified and any of the selection items are omitted, 
the missing selection item assumes its positive form. A selec- 
tion item may appear at most once. 

The selection-items are best explained by describing the effect of their negative form. 

Table 3-2 . Listing Switches 



Switch 


Effect 


MAP 


Output memory map to link summary 


NOMAP 


Suppress memory map 


SYMBOLS 


Output local symbols to symbol table 


NOSYMBOLS 


Suppress local symbols 


PUBLICS 


Output public symbols to symbol table 


NOPUBLICS 


Suppress public symbols 


LINES 


Output line numbers to symbol table (high-level language transla- 
tors only) 


NOLINES 


Suppress line numbers 


IXREF 


Append intermodule cross-reference report to print file 


NOIXREF 


Suppress the intermodule cross-reference report 
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The NOGENERATED control causes RL51 to surpress output of entries whose 
symbol name begins with a question mark (?); such symbols are usually PL/M-51 
generated symbols. The GENERATED form of the control causes RL5 1 to output 
such entries also. 



The NOLIBRARIES control causes RL51 to surpress output of entries whose module 
resides within a library. The LIBRARIES form of the control causes RL51 to include 
all libraries in the IXREF report. 



The selection list is used to control the number of entries collected for the IXREF 
report. This is needed when an excessive number of IXREF entries make it impossi- 
ble for RL5 1 to generate the IXREF report. 



Examples 

Because the default for any listing switch (except IXREF) is the positive form, the 
main use of the switches is to suppress unwanted information. To suppress the entire 
symbol table, for example, the command would be 

RL51 sF1?PR0O.0BJ NOSYHBOLS NOPUBLICS NOLINES 



As another example, to see only the public symbols (no map or other symbols or 
lines), the command is 

RL51 :F1:PR0G.0BJ PRINT C s F 2 ; P R OG . MS 1 ) NOMAP NOSB NOLI 



Note the use of abbreviations (NOSB for NOSYMBOLS and NOLI for NOLINES) 
to save keystrokes. A complete list of abbreviated forms appears at the end of this 
chapter. Note that the blank separating PRINT from its parameters is optional; you 
could also use PRINT(:F2:PROG.M51). 



In order to suppress generated symbols from the IXREF report, the command is 
RL51 ! F1 sPROG.OBJ, ; F 1 ; P R C S . OB J , ; F 1 s P LM B 1 . L I B IXREFCNOGN) 



Using the NOGN (NOGENERATED) selection item prevents PL/M-51 run-time 
library procedures from being written to the IXREF report. 



Linking Controis 

The linking controls allow you to name the resultant output module and to specify 
which debug information is to be copied to the output module. 



NOTE 

In order to obtain the debug information (SYMBOLS, PUBLICS, or 
LINES), the DEBUG control must be included in the invocation line for the 
translator used to produce the input modules. 
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NAME 

The NAME control allows you to name the output module. The format is 

NAME C module-name ) 

If the NAME control is not used, the output module-name defaults to the name of 
the first input module processed. 

Example 

:F1:RLS1 ; F 1 ; S AMP L 1 . B J , : F 1 : S A MP L 2 . OB J TO : F 1 : S A M P L E . ABS I 
**NAMECSAMPLE_PROGRAM) 

In this example, the name SAMPLEJPROGRAM is assigned to the output module. 
Note that the blank between NAME and its parameter is optional and can be omitted 
as shown in the example. 



Linking Switches 

The DEBUGSYMBOLS, DEBUGPUBLICS, and DEBUGLINES controls select 
what kinds of debug information are to be included in the output file. The default of 
any switch is always the positive form (DEBUGSYMBOLS, DEBUGPUBLICS, and 

DEBUGLINES). Table 3-3 summarizes the linking switches. 



Examples 

Because the linking switches default to the positive form, you will usually use the 
negative forms to suppress unwanted debug information in the output file. For 
example, to cause the output file debug information to contain only the information 
for the public symbols, use 

RL51 : F 1 ; PROG 1 . OBJ N D E B U G S Y M B L S NODEBUGLINES 

To have only the local symbols output to the absolute file, use 

RL51 :F1:PR0G1. OBJ NODP NODL 

Note the use of abbreviations (NODP for NODEBUGPUBLICS and NODL for 
NODEBUGLINES). A complete list of abbreviations for command words appears 
at the end of this chapter. 

Table 3-3 . Linkiiig Switches 



Switch 


Effect 


DEBUGSYMBOLS 


Copies local symbol information to output file 


NODEBUGSYMBOLS 


Suppresses local symbols 


DEBUGPUBLICS 


Copies public symbol information to output file 


NODEBUGPUBLICS 


Suppresses public symbols 


DEBUGLINES 


Copies line number information (high-level language translators 
only) to output file 


NODEBUGLINES 


Suppresses line numbers 
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Locating Controls 

The locating controls allow you to assign absolute addresses to relocatable segments, 
to specify the ordering of relocatable segments of a given type in memory, and to 
force allocation of segments into a specific range of addresses. 



Allocation Sequence 

The system allocates memory in accordance with segment attributes and locating 
controls, using a fixed order of precedence. The precedence of the allocating opera- 
tions (grouped by type of memory space) is as follows: 

Internal Data Space: 

Absolute BIT, DATA, and IDATA segments, and register banks 

Segments specified in a PRECEDE control in the RL5 1 command 

Segments specified in a BIT control in the RL51 command 

DATA type segments with relocation equal to BIT- ADDRESSABLE 

Other relocatable bit segments 

Segments specified in a DATA control in the RL51 command 

DATA type segments with relocation equal to UNIT-aligned 

Segments specified in an IDATA control in the RL5 1 command 

Other relocatable IDATA segments, except 7STACK 

Segments specified in a STACK control in the RL51 command 

7STACK, if it is IDATA and has not been specified in any other locate control 

External Data Space: 

Absolute external data segments 

Segments specified in an XDATA control in the RL5 1 command 

Other relocatable external data segments 

Code Space: 

Absolute code segments 

Segments specified in a CODE control in the RL5 1 command 

Other relocatable code segments 



NOTE 

In most cases, the allocation algorithm will produce a workable solution 
without requiring the user to enter any locating controls in the RL5 1 
command. These controls are intended for the experienced user, in cases where 
running RL5 1 without them does not give a good enough result. 



Format Summary 

The locating controls have the format 

control (segment [,».,]) 



where 

segment 



= segment-name i i base-address} 1 
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The segments specified in the locating, controls are allocated in the order they appear; 
the first segment is assigned the lowest possible address, and succeeding segments 
receive higher and higher addresses. 

The user has the option of specifying the base address of any or all segments. Segments 
with specified base addresses must appear in the list in ascending numerical order. 
Segments named in a locating control with a specific base address are allocated at 
that address irrespective of segment overlap or segment type contradiction, as long as 
ascending order is maintained. Base addresses are byte addresses except for the BIT 
locating control, where addresses are bit addresses in the bit space (0 to 127). 



Table of Locating Controls 

Table 3-4 lists the locating controls in order of precedence. The first column gives 
the name of the control. The second column describes the address space affected by 
the control. The third column gives the address range for segments within each control. 
The last column shows what types of segments are allowed for each control; for each 
valid type, the column also shows the allowable relocation attributes. (Refer to the 
MCS-51 Macro Assembler User's Guide and PL/M'51 User's Guide for details on 
segment types and relocation attributes.) 



Notes On Locating Controls 

The following notes refer to table 3-4. 

1 . Bit addresses for non-BIT segments in the BIT control must be on byte bounda- 
ries; that is, they must be divisible by eight. (BIT-type segments can be aligned 
on bit boundaries.) 

2. The range of addresses for the IDATA control is dependent on the target machine. 
See the RAMSIZE control later in this chapter. 

3. The STACK control specifies which segments are to be allocated uppermost in 
the IDATA space. The memory accessed starts after the highest on-chip RAM 
address occupied by any previously allocated segment and continues to the top 
of the IDATA space. 



Table 3-4 . Locating Controls 



Control 


Address Spac® 


Address Range 
(Hex) 


Segment Types 
(and Attributes) 


PRECEDE 


Register banks and bit- 
addressable space In 
on-chip data RAM 


00H-2FH 


DATA (UNIT-aligned); 
IDATA 


BIT 


Bit-addressable space 
in on-chip data RAM 


OOH - 7FH 
(see note 1) 


BIT; DATA; IDATA 


DATA 


Directly-addressable 
on-chip data RAM 


OOH - 7FH 


DATA (UNIT-aligned); 
IDATA 


IDATA 


Indirectly-addressable 
on-chip data RAM 


OOH - OFFH 
(see note 2) 


IDATA 


STACK 


Same as IDATA (see 
note 3) 


Same as IDATA 


Same as IDATA 


XDATA 


External data RAM 


- OFFFFH 


XDATA 


CODE 


Code memory 


- OFFFFH 


CODE 
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NOTE 

This control has no other effect on any segments. 

The ID AT A ? STACK segment, if it exists, is placed higher than segments 
that were mentioned in the STACK control. 

The STACK control provides a convenient way to handle the stack (usually for 
ASM51 -based application, where 7STACK is not used). 

First, assign the stack pointer (SP) to a relocatable segment; consider the following 
ASM51 example: 

STACK_AREA SEGMENT IDATA ; SEGMENT directive in lource. 
DS 10H ; Reserve 16 bytes for stack. 

; Other CODE instructions. 

MOV SP, #STACK_AREA- 1 | Initialize SP. 

Then, at relocation time, specify the segment named STACK_AREA in a STACK 
locating control: 

RL51 ... STACK CSTACK_AREA) 

where 

ellipsis (...) represents the rest of the invocation line exclusive of the 

STACK control. 

NOTE 

If the application contains modules produced by PL/M-51, the 7STACK 
should be used as the stack segment. 

Examples 

Here are three brief examples of invocations with locating controls. See Chapter 5 
for a more extended example. 

RL51 ; F 1 : PROG 1 . OBJ , : F 1 : P R G 2 . B J TO ;F2:PR0G.ABS 4 
^^PRECEDE (MESSAGED XDATA CARRAY1 (256), ARRAY2 (512)) 

In this example, the DATA (or IDATA) segment named MESSAGE 1 will be 
allocated space in on-chip RAM in the lowest available location, overlapping the BIT 
space if necessary. The XDATA control specifies that the two arrays are to be located 
at specific addresses (e.g., for debugging). 

RL51 iF1:TEST.0BJ STACK (STACK_AREA) 

Here, the STACK control allocates the uppermost portion of IDATA space for the 
segment named STACK_AREA. The software definition of STACK_AREA might 
be as given in the previous section. 

RL51 APROG.OBJ, BPROG.OBJ, PLM51.LIB CODE CM0D1 (4000H), 

M0D2, M0D3) 

Here, the CODE control allocates space in code memory for segments MODI, MOD2, 
and MOD3. MODI is aligned at location 4000H. MOD2 and MODS are assigned 
contiguous addresses after MODI. 
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Configuration Controls 

The configuration controls are used to describe the actual configurations that objects 
are aimed to. 

This group contains the RAMSIZE control. 



RAMSIZE 

The RAMSIZE control format 

RAMS I IE (value) 

where 

value is a number in the range 128 to 255. 

RAMSIZE specifies the maximum amount of on-chip RAM that may be allocated 
for the user program. The default value for RAMSIZE is 128 (as is the case for the 
8051). If the object is aimed at more than one configuration of the MCS-51 family, 
specify the MINIMUM of all on-chip RAM sizes among all machines you want to 
link. 

The sole use of this control is to enable RL5 1 to check on-chip memory size constraints 
at RL-time and thus avoid confusion at ICE-time. 



OVERLAY/NOOVERLAY Controls 

The linker allows overlaying of on-chip RAM segments among modules, under the 
specification of the OVERLAY control. Two segments can be overlaid if all the 
following conditions exist: 

^ The segments have the same type (DATA, IDATA, BIT, or BITADDRESS- 

ABLE). 

® The segments use the same register bank (determined by the USING attribute 
or the REGISTERBANK control). 

® The segments are marked as overlayable. Currently, this is done only by the 
PL/M-51 compiler. ASM51 (V2.1 and lower) lacks this feature. Therefore, 
assembler segments are considered non-overlayable. 

® The segments belong to disjoint modules. That is, no procedure in one module 
can directly or indirectly call a procedure from the other. 

The default is NOOVERLAY. No overlaying of on-chip RAM segments is done by 
the linker. 

The general form of the OVERLAY control is as follows: 

OVERLAY [ C overlay-unit [,...])] 

where 

overlay-unit is ov-module-name calls ov-module-name. 

ov-module-name is a legal RL51 module name or *, which stands for all the 
module names. 

calls is > . 
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OVERLAY 

If the OVERLAY control appears in the invocation hne without arguments, the Hnker 
assumes that no intra-module calls exist except for those deducible from the PUBLIC- 
EXTERNAL declarations, and that overlaying of all overlayable segments is safe. 



NOOVERLAY 

The linker does not overlay data segments. 



OVERLAY (A > B) 

If the OVERLAY control appears in the invocation line v^ith arguments, it indicates 
that there are invisible calls between modules. The notation A > B means that module 
A calls module B. In this case, the linker overlays all overlayable segments, except 
that segments from A are not overlaid by segments from B. Note that the added 
connection can prevent other segments from overlaying. For example, if the segment 
A was overlaid with the segment D, and B calls D (visibly by PUBLIC-EXTERNAL 
declarations), then the effect of A > B is that A and D will not be overlaid, since A 
can call D through B. 



OVERLAY (A > *, * > B) 

A module can be declared as non-overlayable in two ways. The argument A > * 
indicates that the module A calls all other modules. On the other hand, * > A means 
every module calls A. In either case, no segments from A will be overlaid. The effect 
of each form depends on the nature of A. For example, if the * > A form is used and 
A visibly calls all other modules, then every module can call (through A) each other 
module. In this case, the linker will not perform any overlays. 

The overlaying of data segments in on-chip RAM has the following restrictions: 

• The OVERLAY control cannot be invoked with the IXREF selection items 
NOGENERATED or NOLIBRARIES. RL51 generates an error if either one 
is specified. 

• Combined segments and segments appearing in locating controls are not overlaid 
by the linker. 

Following is an example in which two disjoint modules share the same on-chip RAM 
area: 

modi; DO ; 

THREE_BEARSi PROCEDURE PUBLIC; 

DECLARE L I TTLE_BEARS_BED BYTE; 

IF BOOLEAN ( L I T T L E_B E A R S_B E D ) THEN 

CALL MSGCoC^SOMEONE^^S BEEN IN MY BEDIM, 0) 

L I TTLE_BE ARS_BED - ; 
END THREE_BEARS; 

END modi; 
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mo d 2 : DO 



GOLDILOCKS: PROCEDURE PUBLIC 
DECLARE SPARE_BED BYTE; 
SP ARE_BED = 1 ; 

END GOLDILOCKS; 



END mod2 ; 

m a i Ti_5 t r y : DO 



THREE_BEARS: PROCEDURE EXTERNAL; END 
GOLDILOCKS: PROCEDURE EXTERNAL; END; 

CALL THREE_BEARS; 
CALL GOLDILOCKS; 
CALL THREE_BEARS; 



END m a i ti_5 tor 



In this example, the linker reserves the right to use the LITTLE_BEARS_BED as a 
SPARE_BED because the two procedures are never active simultaneously. 



To perform overlaying, the linker must determine which procedures are active simul- 
taneously. To do this, the linker assumes that all CALLs can be executed. For example, 
if procedure A calls procedure B, and B calls procedures C and D, then the linker 
can overlay RAM variables from C only with the RAM variables of D. 



The linker, however, looks only at the PUBLIC-EXTERNAL declarations. It assumes 
that any reference to an EXTERNAL procedure will be executed, but ignores the 
possibility of hidden calls. The arguments to the OVERLAY control are therefore 
needed to specify those interconnections between modules that cannot otherwise be 
detected by the linker. 



Such situations arise if the interconnection is done by a computed call to an external 
procedure whose address is not determined by a simple PUBLIC-EXTERNAL 
relationship. For example, module A imports from module B a public variable that 
contains the address of a local or public procedure in B. Module A then performs a 
computed call to the procedure in B. The rule can be stated as follows: The linker 
assumes a connection from module A to module B if there exists an external refer- 
ence in A to a public procedure in B. In all other cases, hidden connections must be 
explicitly given as arguments to the OVERLAY control. 



Following is an example of a computed call to an external procedure: 
MOD 1 : DO ; 

DECLARE I_0_CLEAR WORD EXTERNAL; 

CALL I_0_CLEAR; 
END MOD 1 ; 
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In another module, you have: 

M0D2 : DO ; 

DECLARE I_0_CLEAR WORD PUBLIC; 

READER 1 PROCEDURE; 

I_0_ERROR ; PROCEDURE ; 

END I_0_ERROR; 

I_0_SUCCESS : PROCEDURE ; 

END I_0_SUCCESS; 

IF ERR_CODE <> 

THEN I_0_CLEAR = .I_0_ERROR; 
ELSE I_0_CLEAR = . I_0_S U C C E S S ; 

END READER ; 

END M0D2 ; 

In the above procedure, MODI invokes a procedure defined in MOD2. To prevent 
the linker from overlaying on-chip RAM variables of M0D2 with on-chip RAM 
variables of MODI, the following form of the OVERLAY control must be used: 

OVERLAY (MOD 1 > M0D2) 

Overlaying can be a good way of economizing on-chip RAM space; however, overlay- 
ing may, in some cases, give worse results. For example, if most procedures call one 
another, the resulting segments will expand, making it more difficult for the linker to 
allocate a few large segments than many small ones. 

The outcome of the overlaying process can be checked by inspecting the link map. 
All overlaid segments are indicated by **OVERLAP**. Warning (4), DATA SPACE 
MEMORY OVERLAP, is not generated for those segments. 

Abbreviations for Command Words 

Most of the command words in the RL51 command have short forms to save you 
keystrokes over the full spellings. Here is a list of the command words and their 
abbreviations. 



Command Word 


Abbreviation 


BIT 


BI 


CODE 


CO 


DATA 


DT 


DEBUGLINES 


DL 


DEBUGPUBLICS 


DP 


DEBUGS YMBOLS 


DS 


GENERATED 


GN 


I DATA 


ID 


IXREF 


IX 
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Command Word 


Abbreviation 


LIBRARIES 


LB 


LINES 


LI 


MAP 


MA 


NAME 


NA 


NODEBUGLINES 


NODE 


NODEBUGPUBLICS 


NODP 


NODEBUGSYMBOLS 


NODS 


NOGENERATED 


NOGN 


NOIXREF 


NOIX 


NOLIBRARIES 


NOLB 


NOLINES 


NOLI 


NOMA? 


NOMA 


NOOVERLAY 


NOOL 


NOPRINT 


NOPR 


NOPUBLICS 


NOPL 


NOSYMBOLS 


NOSB 


OVERLAY 


OL 


PAGEWIDTH 


PW 


PRECEDE 


PC 


PRINT 


PR 


PUBLICS 


PL 


RAMSIZE 


RS 
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RL51 OUTPUTS 



The RL51 program produces three outputs: console displays, a listing file, and the 
absolute object module file. This chapter describes these outputs and gives examples. 
As discussed in Chapter 3, the listing controls in the RL51 command allow the user 
to suppress some information in the listing file, and the linking controls can suppress 
some information in the absolute object file. 



Console Display 

The console displays produced by RL51 consist of a sign-on message and any error 
messages that occur. The sign-on is as follows: 

ISIS-II MCS-51 RELOCATOR AND LINKER Vx.y 

where 

x.y is the version number. 



Listing File 

RL51 produces a listing file unless it is suppressed in the RL51 invocation. The RL51 
listing file contains: 

® A summary of the link and locate process 

® A symbol table, as specified in the RL5 1 invocation 

® An inter-module cross-reference listing (IXREF) 

• Error messages detected by RL5 1 



Link Summary 

A sample of a link summary is shown in figure 4-1. The summary includes the follow- 
ing kinds of information: 

® A header echoing the RL5 1 invocation. 

• Input modules included in the link process. Input modules are identified by module 
name and file name. 

® A link map (unless suppressed by the NOMAP control). The map lists all 
allocated segments, giving the type, base address, and length of each segment. 
The map also identifies segment overlaps and gaps in the memory space. 

® A list of segments that were ignored in the link process. If any segments were 
ignored, the reasons for doing so will be reported later as an error. 

® A list of unresolved external symbols. An external symbol is unresolved when it 
is not matched by a public symbol in one of the input modules. Each occurrence 
of an unresolved external symbol in a module will be reported later as an error. 

® A list of all symbols that were ignored in the locate process. A symbol is ignored 
when the same name appears as a public symbol in different modules, or has 
attributes that are incompatible with external references, or belongs to an ignored 

segment. Each occurrence of an ignored symbol in a module will be reported 
later as an error. 
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ISIS-II MCS-51 RELOCATQR AND LINKER, VKO, INVOKED BYi 

RL51 s F 1 : F I LE 1 = EXT(M0D1 , M0D2) , : F 1 ? F I L E 2 » E X T TO OUTFIL»EXT & 

NAME (EXAMPLE) MAP PRINT i iLP i) 

I NPUT MODULES I NCLUDED 
F I LE 1 . EXT(M0D1 ) 
F I LE 1 . EXT(M0D2) 
F I LE2 . EXT(M0D3) 

LINK MAP FOR U T F I L . E X T ( E X A M P L E ) 

TYPE BASE LENGTH RELOCATION SEGMENT NAME 



REG OOOOH 0008H "REGBANKO* 

DATA 0008H 0010H UNIT DATA_SEG_1 

DATA 00 1 4H 0008H ABSOLUTE 

*^OVERLAP^^REG 0018H 0008H "REGBANK3' 

BIT 0020H 0001H.6 UNIT A_BIT_SEG 

0021H.6 OOOOH, 2 *^ tQ^p t t # 

DATA 0022H 0001H BITADDR DATA_SEG_2 

DATA 0023H OBH ABSOLUTE 

IDATA 002EH 0042H UNIT STACK_SEG 

0070H 00 1 OH # t f GAP t # f 

XDATA OOOOH COOOH UNIT DYNAMIC_MEM 

CODE OOOOH 1 389H UNIT PROC 1 

1 389H 0477H ^ t # GAP* ♦ * 

CODE 1800H 07A5H INBLOCK PR0C2 

IGNORED SEGMENTS 
DYNAM I C POOL 

UNRESOLVED EXTERNAL SYMBOLS 
INVERT 

IGNORED SYMBOLS 
BIT256 

Figure 4-1 » Link Summary 



NOTE 

1 . For bit addresses, the display format is byte-address. bit-address (example: 
0020H.7 for bit 7 of byte 0020H). However, when bit of a byte is 
referenced, only the byte address is displayed (the .0 is not displayed). 

2. References to an unresolved external symbol, an external symbol refer- 
ring to an ignored public symbol, or a reference to an ignored segment 
will produce additional error messages. 



Symbol Table 

The listing file contains a symbol table as specified by the SYMBOLS, PUBLICS, 
and LINES controls in the RL51 invocation. A sample symbol table is shown in 
figure 4-2. 
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SYMBOL TABLE FOR U T F I L E « E X T C E X A M P L E ) 
VALUE TYPE NAME 



MODULE MEMRY 

Ds0032H PUBLIC LON_MEM_PTR 

BsOOaOH PUBLIC INIT_FLAG 

BsOOaOH.1 PUBLIC FULL_FLAG 

Ds0034H PUBLIC HIGH_MEM_PTR 

XsOOOOH PUBLIC D Y N A M I C_M E M R Y 

PROC ALLOCATE 

D;0064H SYMBOL NUM_BYTES 

D?0068H SYMBOL P L_S E L E C T R 

Ds0068H SYMBOL ALLOC_PTR 

B s 0020H , 2 SYMBOL FLAG 

C ; OOOOH L INE# 19 

C 2 007H L I NE# 20 

CsOOIOH LIHE# 21 

C s 00 13H LINE' 22 

DO 

DsOOSAH SYMBOL I 

C s 00 18H LINE' 23 

C s 002 1 H LI NE# 24 

C 5 0028H L I NE# 25 

C s 002FH L INE# 26 

C I 0032H LINE' 27 

ENDDO 

C s 0037H LINE' 28 

Ci 0040H LINE' 29 

C s 004FH L INE' 30 

C I 0057H LI NE' 3 1 

C I 005FH L I NE' 32 

C % 0088H L I NE' 33 

C I 006FH L I NE' 34 

C s 0078H LI NE' 35 

C I 0082H LINE' 36 

C I 008FH L I NE' 37 

C \ 0094H L I NE' 38 

"- ENDPROC ALLOCATE 

ENDMOD MEMRY 



Figure 4»2. Symbol Table 



NOTE 

The information in the listing file is taken from the input object modules. If 
these are generated without the DEBUG option, the SYMBOLS, PUBLICS, 
and LINES information will not be available for listing. 



The symbol table contains scope definitions and information about the symbols and 
line numbers. Scope definition identifies the module, DO block or procedure that 
contains the symbol or line nurtiber. Note that when the table contains only public 
symbols (i.e., NOSYMBOLS and NOLINES controls are in effect), scope definition 
is by module only. 



4.3 



RL51 Outputs MCS®-51 

Each entry in the table consists of three parts, as follows: 

® VALUE. The value is the absolute address of the symbol. The address is prefixed 
with a letter indicating the type of address space (C, code; D, internal data; I, 
indirect internal data; B, bit space; X, external data; N, typeless number). A byte 
address (or a bit address on a byte boundary) is shown as a four-digit hexadecimal 
number (example: OOEOH). A bit address (unless it is on a byte boundary) is 
shown as a byte address followed by a period and the bit offset (1 through 7) 
into the byte. 

TYPE. The type field identifies the entry as a local symbol (SYMBOL), a public 
symbol (PUBLIC), segment (SEGMENT), or a line number (LINE#). 

® NAME. The name field gives the name of the symbol, or the number of the line. 

For scope definition, a line is printed for the beginning and end of each block. The 
TYPE field shows the type of block (MODULE, DO, or PROC for PROCEDURE), 

and the end of each block (ENDMOD, ENDDO, ENDPROC). The NAME field 
shows the name of the block, if any. 

NOTE 

Line number information and scope definitions other than MODULE are 
applicable only to object files produced by high-level language translators 

(e.g.,PL/M-51). 



Inter-Module Cross-Reference Report (IXREF) 

The listing file contains an IXREF report as specified by the IXREF control and its 
associated selection list in the RL51 invocation. A sample IXREF report is shown in 
figure 4-3. 

The IXREF report consists of an alphabetically sorted list of symbols. Each such 
symbol begins a new line and represents a symbol that was declared as PUBLIC or 
EXTERNAL in at least one of the input modules. Each symbol is followed by its 
corresponding address space, followed by a semicolon. To the right of the semicolon 
starts a list of modules in which the symbol was declared PUBLIC or EXTERNAL. 
The first module name in the list is the one in which the symbol was declared PUBLIC. 
If a symbol is unresolved, or if a symbol is defined in a library and the NOLIBRAR- 
lES selection item is in effect, then the string ** UNRESOLVED ** appears in front 
of the modules list. 



Error Messages 

RL5 1 displays error messages on the console and copies them to the end of the listing 
file unless the listing file is suppressed. 

RL5 1 error messages describe warnings, errors, and fatal errors. A warning is a 
detected condition that may or may not be what the user desired; a warning does not 
terminate the link/locate operation. An error does not terminate operation, but 
probably results in an output module that cannot be used. A fatal error terminates 
operation of RL5 1 . 

Refer to Appendix B for a list of the error messages and probable causes. 
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INTER-MODULE CROSS-REFERENCE LISTING 



NAME . USAGE 



MODULE NAMES 



? CHE CK_EQ? BYTE e . 
?CHECK_EQ_BI TS?BIT 
?P00 08 



?P00 1 5 , . , 

?P00 16 » . . . 

?PI HOR . . . 

?P I VOR , . , . 

?PSWOR , . . . 

CHECK_EQ. . . 
CHECK_EQ_BITS 

CHECK_EKIT. . 

CHECK_INIT, 3 

PUBOO , , . . 

PUB01 . , . . 

PUB 2 . . , 

PUB03 , . . , 

PUB04 . , . , 

PUB05 . , . , 

PUBOS . . . , 

PUB07 . , . , 

PUB08 . , . . 

PUB09 , , . . 

PUB1 , . » . 

PUB1 1 . . , . 

PUB1 2 , , , . 

PUB1 3 . . . e 

PUB1 4 , . . 

PUB1 5 , . . . 
PUB16 .... 

PUB17 , , . . 

PUB18 . , . 

PUB19 , . . « 

PUBXO , . « . 

PUBX1 . . . . 

PUBYO , . . 

PUBZO , . , , 



DATA 

BITi 

CODE 

CODE 

CODE 

CODE 

CODE 

NUMB 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

XDATA 

DATA 1 

IDATA 

BIT 1 

NUMB 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 

CODE 



CHKE 
CHKE 
?P00 
?P00 
?P00 
TESB 
?P I V 
TESB 
CHKE 
CHKE 
CHKE 
CHKE 
MODU 
MODU 
MODU 

# t u 

MODU 

MODU 

# # y 

MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
MODU 
t f u 

# * U 



Q 

Q 

08 

15 

16 

AS 

OR 

AS 

Q 

Q 

Q 

Q 

LE 

LE_ 

LE_ 

NRE 

LE_ 

LE_ 

NRE 

LE_ 

LE_ 

LE_ 

LE_ 

LE_ 

LE_ 

LE 

LE_ 

LE_ 

LE 

LE 

LE 

LE_ 

LE_ 

LE_ 

NRE 

NRE 



TESBAS 

TESBAS 
TESBAS 
TESBAS 
?P I VOR 
TESBAS 
?P I VOR 
TESBAS 



MODULE_ 

MODULE. 

MODULE_ 
OLVED ^* 

MODULE_ 

MODULE_ 
OLVED ** 

MODULE. 

MODULE. 

MODULE. 



MODULE. 2 

MODULE. 2 

MODULE. 2 
MODULE. 1 MODULE. 2 

MODULE. 2 

MODULE. 2 
MODULE. 1 MODULE. 2 

MODULE. 2 

MODULE. 2 

MODULE. 2 



MODULE.O 

MODULE. 
OLVED *^ MODULE. 1 
OLVED ** MODULE. 1 



M0DULE_2 



Figure 4-3 , IXREF Listing 



Absolute Object File 

The linking and locating process combines one or more relocatable object files into 
one absolute object file. The absolute object file contains one module; the absolute 
module consists of 

• A module header record that identifies the module. 

• A set of intermixed content and debug records. The content records contain the 
program code. The debug records contain the location and scope of local symbols, 
public symbols, segment symbols, and line numbers, as specified by the DEBUG- 
SYMBOLS, DEBUGPUBLICS, and DEBUGLINES controls in the RL51 
invocation. 

® A module end record that verifies the module name. 
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CHAPTER 5 
EXAMPLES OF PROGRAM DEVELOPMENT 



This chapter shows three brief examples of program development using ASM51, 
PL/M-51, and RL51. The first example is the sample program discussed in the 
ASM51 User's Guide; the example shows how to assemble each of the three modules, 
then link and locate them into a single absolute object module with RL51. The second 
example is a short program that illustrates the use of the locating controls. The third 
example shows the use of RL51 with PL/M-51 modules, emphasizing the library 
process. 



Using Multiple Modules 



The first example is a program of three modules, named SAMPLE, CONSOLE_IO, 
and NUM_CONVERSION. The source for these modules is in three files, 
SAMP1.A51, SAMP2.A51, and SAMP3.A51, respectively. To assemble these 
modules, invoke the assembler as follows: 

s F 1 s ASH51 s F1 ! SAMP 1 . AE1 DEBUG 

s F 1 s ASN51 s F 1 s SAMP2 . AB1 DEBUG 

sFlsASMSi jF1sSAMP3.AS1 DEBUG 



Note that this example assumes the three source files are on the same drive as the 
assembler and linker/locator, and that the output file will be sent to the same drive. 
The assembler invocations use the DEBUG control to have the symbol tables output 
to the object files for the three modules. 



After assembly is complete, the system has created object files SAMP 1. OB J, 
SAMP2.0BJ, and SAMP3.0BJ, and listing files SAMPl.LST, SAMP2.LST and 
SAMP3.LST. The three listing files are shown in figures 5-1, 5-2, and 5-3. 



To link and locate the three modules, enter the command 

;F1;RLS1 ; F 1 ; S AMP 1 . Q B J , ; F 1 : S AM P 2 . OB J , ; F 1 : S AMP 3 . B J I 

^nO :F1 ! SAMPLE I 

^^PRINT C ! F1 sSAMPLE.LST) SYMBOLS LINES PUBLICS. 



After the RL51 program has executed, the system has placed the absolute object 
module in file SAMPLE, and an output file with information on the link and locate 
process in file SAMPLE. LST. The output file also contains symbol table information 
as requested by the SYMBOLS, LINES, and PUBLICS controls. The listing file is 
shown in figure 5-4. 
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MCS-51 MACRO ASSEMBLER SAMPLE 

ISIS-II MCS-51 MACRO ASSEMBLER V2 « 

OBJECT MODULE PLACED IN : Fl : SAMPl » OB J 

ASSEMBLER INVOKED BY: :F1:ASM51 : Fl : SAMPl , A51 DEBUG 

LOC OBJ LINE SOURCE 



0000 

0000 758920 
0003 758D03 
0006 7598DA 
0009 D28E 



000B 900000 F 
000E 120000 F 
0011 120000 F 



0014 


900000 


F 


0017 


120000 


F 


001A 


120000 


F 


001D 


7800 


F 


001F 


120000 


F 


0022 


120000 


F 


0025 


900000 


F 


0028 


120000 


F 


002B 


120000 


F 


002E 


7800 


F 


0030 


120000 


F 


0033 


120000 


F 



0036 7900 F 

0038 120000 F 

003B 7900 F 

003D 120000 F 



0040 E500 
0042 2500 
0044 F500 

0046 7900 
0048 120000 

004B 900000 
004E 120000 
0051 7900 
0053 7A04 
0055 120000 
0058 80B1 



0008 



F 
F 
F 

F 
F 

F 
F 
F 



1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 

46 
47 
48 
49 
50 
51 
52 
53 
54 
55 
56 
57 
58 
59 



NAME SAMPLE 



E 
E 

CSEG 
} Th 
; al 
ORG 
MOV 
MOV 
MOV 
SETB 



XTRN code (put_crlf, put_string , put_data_str ) 
XTRN code (get num, binasc, ascbin) 



is is the initializing section. Execution 
ways starts at address on power-up » 


Set timer to auto-reload 
Set timer for 110 BAUD 
Prepare the Serial Port 
Start clock 



TMOD, #001000008 
THl,#(-253) 
SCON, #110110108 
TRl 



This is the main program. It's an infinite loop, 
where each iteration prompts the console for 2 
input numbers and types out their sum. 

START: 

; Type message explaining how to correct a typo 

MOV DPTR,#typo_msg 

CALL put_string 

CALL put_crlf 

; Get first number from console 

MOV DPTR, #numl_msg 

CALL put_string 

CALL put_crlf 

MOV R0,#numl 

CALL get_num 

CALL put_crlf 

} Get second number from console 

MOV DPTR, #num2_msg 

CALL put_string 

CALL put_crlf 

MOV R0,#num2 

CALL get_num 

CALL put_crlf 

I Convert the ASCII numbers to binary 

MOV Rl,#numl 

CALL ascbin 

MOV Rl,#num2 

CALL ascbin 

} Add the 2 numbers, and store the results in SUM 

MOV a,numl 

ADD a,num2 

MOV sum, a 

I Convert SUM from binary to ASCII 

MOV Rl,#sum 

CALL binasc 

; Output sum to console 

MOV DPTR,#sum_msg 

CALL put_string 

MOV Rl,#sum 

MOV R2,#4 

CALL put_datd_str 

JMP start 



DSEG at 8 
STACK: DS 8 



At power-up the stack pointer is 
initialized to point here. 



Figire 5-1 , SAMPl Listing File 
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0000 




0004 




0008 




0000 


54595045 


QiidQA 


205E5820 


0008 


544F2052 


000C 


45545950 


0010 


45204120 


0014 


4E554D42 


0018 


4552 


001A 


00 


001B 


54595045 


001F 


20494E20 


0023 


46495253 


0027 


54204E55 


002B 


4D424552 


002F 


3A20 


0031 


00 


0032 


54595045 


0036 


20494E20 


003A 


5345434F 


003E 


4E44204E 


0042 


554D4245 


0046 


523A20 


0049 


00 


004A 


54484520 


004E 


53554D20 


0052 


495320 


0055 


00 



60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 



71 



72 



73 



74 
75 



DATA_AREA segment DATA 

CONSTANT_AREA segment CODE 



RSEG 
NUMls 
NUM2: 
SUM: 



clata_area 
DS 4 
DS 4 
DS 4 



RSEG constant_area 

TYPO_MSGl DB 'TYPE X TO RETYPE A NUMBER', 00H 



NUMl MSGs DB 'TYPE IN FIRST NUMBER". ',00H 



NUM2_MSG: DB 'TYPE IN SECOND NUMBER: ',00H 



SUM MSG: DB 'THE SUM IS ',00H 



END 



SYMBOL TABLE LISTING 



NAME 



TYPE 



VALUE 



ATTRIBUTES 



ASCBIN, 

BINASC, 

CONSTANT_AREA 

DATA_AREA 

GET_NUM 

NUM1_MSG 

NUMlo o 

NUM2_MSG 

NUM2o . 

PUT_CRLF 

PUT_DATA_STR 

PUT_STRING» 

SAMPLE 

SCONo 



STACK 
START 
SUM_MSG 
SUM , 
THl . 
TMOD. 
TRl . 
TYPO MSG 



C ADDR 
C ADDR 
C SEG 
D SEG 
C ADDR 
ADDR 
ADDR 
ADDR 
ADDR 
ADDR 
ADDR 
ADDR 



EXT 
EXT 



D ADDR 
D ADDR 
C ADDR 
C ADDR 
D ADDR 
D ADDR 
D ADDR 
B ADDR 
G ADDR 



0056H 
000CH 

001BH 
0000H 
0032H 
0004H 



0098H 

0008H 

000BH 

004AH 

0008H 

008DH 

0089H 

0088H« 

0000H 



EXT 



EXT 
EXT 
EXT 



REL=UNIT 
REL=UNIT 

SEG=CONSTANT_AREA 
SEG=DATA_AREA 
SEG=CONSTANT_AREA 
SEG=DATA AREA 



SEG=CONSTANT_AREA 
SEG=DATA AREA 



SEG=CONSTANT AREA 



REGISTER BANK(S) USED: 0, TARGET MACHINE(S); 
ASSEMBLY COMPLETE, NO ERRORS FOUND 



8051 



Figure 5-1 . ' SAMPl Listing File (Cont^d . 
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MCS®-51 



ISIS-II MCS-5i MACRO ASShiMBLER V2 . 

OBJECT MODULE PLACED IN 2 Fl : SAnP2 , OB J 

ASSEMBLER INVOKED BY: :FlsASM5i '. Fl s SAMP2 » A51 DEBUG 



LOC OBJ 



000D 


000A 


0000 


740D 


0002 


120000 


0005 


740A 


0007 


120000 


000A 


22 



000B E4 
000C 93 
000D 6006 
000F 120000 

0012 A3 

0013 80F6 

0015 22 



0016 E7 

0017 120000 
001A 09 
001B DAF9 
001D 22 



001E 3099FD 
0021 C299 
0023 F599 
0025 22 



0026 7A04 
0028 A900 
restart 

002A 120000 



LINE 

1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 
42 
43 
44 
45 
46 
47 
48 
49 
50 
51 
52 
53 
54 
55 

56 
57 
58 



SOURCE 

NAME CONSOLE_IO 
} 
IO_ROUTINES segment CODE 

RSEG IO_ROUTINES 
I This is the console 10 routine cluster, 

PUBLIC put_crlf, put_str ing ,put_data_str ,get_num 

USING 

This routine outputs a Carriage Return and 

a Line Feed 
PUT_CRLF: 

CR EQU 0DH ; carriage return 

LF EQU 0AH ; line feed 

MOV A,#cr 
CALL put_char 
MOV A,#lf 
CALL put_char 
RET 

Routine outputs a null- terminated string located 
in CODE memory, whose address is given in DPTR. 
PUT_STRING: 

CLR A 

MOVC A,(aA+DPTR 

JZ exit 

CALL put_char 

INC DPTR 

JMP put_string 
EXIT: 

RET 

Routine outputs a string located in DATA memory, 
whose address is in Rl and its length in R2 . 
PUT_DATA_STR: 

MOV A,(aRl 

CALL put_char 

INC Rl 

DJNZ R2,put_data_str 

RET 

Routine outputs a single character to console. 
The character is given in A. 
PUT_CHAR: 

JNB TI,$ 

CLR TI 

MOV SBUF,A 

RET 

Get a 4 character string from console 
and stores it at the address given in R0 , 
If a X is received, routine starts over again. 
GET_NUM: 

MOV R2,#4 ; set up string length as 4 

MOV R1,AR0 ; R0 value may De needed for 

GET_LOOP: 

CALL get_char 
; Next 4 instr's handle X- the routine starts 



Figures-!. SAMP2 Listing File 
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59 


', over 


if received 


002D 


C2E7 




60 


CLR ACCo7 ; clear th 


002F 


B41805 




61 


CJNE A,#18H.G0 ON } if not 
CALL put_crif - 


0032 


120000 


F 


62 


0035 


80EF 




63 


JMP get num 








64 


GO ONi 




0037 


F7 




65 


MOV 


(§R1,A 


0038 


09 




66 


INC 


Rl 


0039 


DAEF 




67 


DJNZ 


R2 ^get_loop 


003B 


22 




68 
69 


RET 










70 


; Get a 


single character from console 








71 


; The c 


haracter is returned in A. 








72 


GET CHARS 


003C 


3098FD 




73 


JNB 


RI.$ 


003F 


C298 




74 


CLR 


RI 


0041 


E599 




75 


MOV 


A^SBUF 


0043 


22 




76 
77 
78 


RET 
END 





SYMBOL TABLE LISTING 



NAME 


T 


Y P E 


V A L 


U E 




ACC 


D 


ADDR 


00E0H 


A 




AR0 


D 


ADDR 


0000H 


A 




CONSOLE 10 o 














CR 




NUMB 


000DH 


A 




EXIT ...» 


C 


ADDR 


0015H 


R 




GET CHAR . . 


C 


ADDR 


003CH 


R 




GET LOOP . , 


C 


ADDR 


002AH 


R 




GET NUM, . , 


C 


ADDR 


0026H 


R 


PUB 


GO ON, , , . 


C 


ADDR 


0037H 


R 




10 ROUTINES, 


C 


SEG 


0044H 






LF 




NUMB 


000AH 


A 




PUT CHAR , , 


C 


ADDR 


001EH 


R 




PUT CRLF , , 


C 


ADDR 


0000H 


R 


PUB 


PUT DATA STR 


C 


ADDR 


0016H 


R 


PUB 


PUT STRING , 


C 


ADDR 


000BH 


R 


PUB 


RI 


B 


ADDR 


0098H. 


A 




SBUF , , , , 


D 


ADDR 


0099H 


A 




TI 


B 


ADDR 


0098H, 


1 A 





ATTRIBUTES 



SEG = IO_ROUTI.NES 
SEG=IO_ROUTINES 
SEG=IO_ROUTINES 
SEG=IO_ROUTINES 
SEG=IO_ROUTINES 
REL=UNIT 

SEG=IO_ROUTINES 
SEG=IO_ROUTINES 
SEG=IO_ROUTINES 
SEG=IO ROUTINES 



REGISTER BANK(S) USED? 0, TARGET MACHINE(S)s 8051 
ASSEMBLY COMPLETE, NO ERRORS FOUND 



. Figure 5=2 o SAMP2 Listieg File (ContM . 
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MCS®.51 



MCS-51 MACRO ASSEMBLER 



NUM CONVERSION 



ISIS-II MCS-51 MACRO ASSEMBLER V2 , 

OBJECT MODULE PLACED IN : Fl : SAMPS . OBJ 

ASSEMBLER INVOKED BY; :F1:ASM51 i Fl : SAMPS . A51 DEBUG 



LOC OBJ 



LINE 



SOURCE 



00S0 
002B 
002D 



0000 A80i 

REG 
0002 08 
000S E6 

0004 CS 

0005 94S0 
0007 75F064 
000A A4 
000B FB 

000C 08 
000D E6 
000E 94S0 
0010 75F00A 
001S A4 

0014 2B 

0015 FB 

0016 08 

0017 E6 

0018 CS 

0019 9430 
001B 2B 
001C FB 



001D E7 
001E B42D04 

0021 EB 

0022 F4 
002S 04 
0024 FB 



1 
2 
S 
4 
5 
6 
7 
8 
9 
10 
11 
12 
IS 
14 
15 
16 
17 
18 
19 
20 
21 
22 
2S 
24 
25 
26 
27 
28 
29 
S0 
SI 
S2 
SS 
S4 
S5 
S6 
S7 
S8 
S9 
40 
41 
42 
4S 
44 
45 
46 
47 
48 
49 
50 
51 
52 
5S 
54 
55 
56 
57 
58 
59 
60 



NAME NUM_CONVERSION 

} 

NUM_ROUTINES segment CODE 
RSEG NUM_ROUTILsIES 
Tnis module converts from ASCII to oinary 
and backo The binary numbers are signed one-byte 
integers, i.e. range is -128 to +127. Their 
ASCII representation is always 4 char's long- 
i.e, a sign followed by S digits. 
PUBLIC ascbin, binasc 
USING 
ZERO EQU '0' 
PLUS EQU '+' 
MINUS EQU '-' 

This routine converts ASCII to binary. 
INPUT- a 4 char string pointed at by Rl. The 
number range must be -128 to +127, and the 
string must have S digits preceded by a sign. 
OUTPUT- a signed one-byte integer, located where 
the input string started (pointed at by Rl) . 
ASCBIN: 

MOV R0,AR1 ; Rl original value needed later 
; Compute first digit value, and store it in TEMP 
TEMP EQU RS 

INC R0 

MOV A,(aR0 

CLR C 

SUBB A,#zero 

MOV B,#100 

MUL AB 

MOV TEMP, A 
; Compute the second digit value 

INC R0 

MOV A,(aR0 

SUBB A,#zero 

MOV B,#10 

MUL AB 
; Add the value of the second aigit to num. 

ADD A, TEMP 

MOV TEMP, A 
; Get third digit and its value to total 

INC R0 

MOV A,@R0 

CLR C 

SUBB A,#zero 

ADD A, TEMP 

MOV TEMP, A 
} Test the sign and complement the number if the 
} sign is a minus 



MOV A,@R1 

CJNE A,#minus,pos 



;Skip the next 4 instr's 
;if the number is positive 



MOV 


A, TEMP 


CPL 


A 


INC 


A 


MOV 


TEMP, A 



} Epilogue- store the result and exit 
POS: 



Figure 5-3 . SAMP3 Listing File 
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0025 EB 

0026 F7 

0027 22 



00E7 

0028 E7 

0029 772B 

002B 30E704 

002E 772D 

0030 14 

0031 F4 



0032 09 

0033 75F064 

0036 84 

0037 2430 

0039 F7 

003A 09 
003B E5F0 
003D 75F00A 

0040 84 

0041 2430 

0043 F7 

0044 09 

0045 E5F0 
0047 2430 
0049 F7 

004A 22 



61 


MOV 


A, TEMP 


62 


MOV 


@R1,A 


63 


■RET 




64 






65 


This 


routine co 


66 


INPUT 


-a signed 


67 


OUTPUT- a 4 cha 


68 


in 


put number 


69 BINASCs 




70 SIGN t>it ACCo7 


71 


} Get the numlDer , 


72 


MOV 


A, (SRI 


73 


MOV 


(aRl,#plus 


74 






75 


JNB 


s i 9 n , g o_o 


76 


; Next 


3 instruct 


77 


MOV 


(aRl,#minu 


78 


DEC 


A 


79 


CPL 


A 


80 


} Facto 


r out the 


81 GO 0N2: 




82 


INC 


Rl 


83 


MOV 


B,#100 


84 


DIV 


AB 


85 


ADD 


A,#zero 


86 


MOV 


(aRl.A 


87 


, Factor out the 


88 


INC 


Rl 


89 


MOV 


A,B 


90 


MOV 


B,#10 


91 


DIV 


AB 


92 


ADD 


A,#zero 


93 


MOV 


@R1,A 


94 


; Store 


the third 


95 


INC 


Rl 


96 


MOV 


A,B 


97 


ADD 


A^ #zero 


98 


MOV 


@R1,A 


99 


} note 


that we re 


100 


RET 




101 






102 


END 





nverts Dinary to ASCII. 
1-hyte integer^ pointed at t>y Rl 
racter string, located where the 
was (pointed at iDy Rl) » 



find its sign and store its sign 

} Store a plus sign (over- 
iwritten hy minus if needed) 
n2 ;Test the sign hit 

ions handle negative numiDers 
s ;Store a minus sign 



first digit 



;store the first digit 
second digit 



;store the second digit 



dig it 



jstore the third digit 
turn without restoring Rl 



SYMBOL TABLE LISTING 



NAME 



TYPE 



VALUE 



ATTRIBUTES 



ACC D ADDR 

ARl D ADDR 

ASCBIN . o » , C ADDR 

Bo . . o o o o D ADDR 

BINASC , , o o C ADDR 

G0_0N2 o o . « C ADDR 

MINUS NUMB 

NUM_CONVERSION 

NUM_ROUTINES o C SEG 

PLUS . o . o o NUMB 

POS C ADDR 

SIGN B ADDR 

TEMP REG 

ZERO NUMB 



REGISTER BANK(S) USED: 0, TARGET MACHINE (S)i 8051 
ASSEMBLY COMPLETE, NO ERRORS FOUND 



00E0H 


A 






0001H 


A 






0000H 


R 


PUB 


SEG=NUM ROUTINES 


00F0H 


A 






0028H 


R 


PUB 


SEG=NUM ROUTINES 


0032H 


R 




SEG=NUM ROUTINES 


002DH 


A 






004BH 






REL=UNIT 


002BH 


A 






0025H 


R 




SEG=NUM ROUTINES 


00E0Ho' 


7 A 






R3 








0030H 


A 







Figure 5-3 . SAMP3 Listing File (ContM . ) 
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ISIS-II RL51 PAGE 



ISIS-II MCS-51 RELOCATOR AND LINKER, V2 . , INVOKED BY: 

:F1: RL5i :F1: SAMPl.OBJ, :F1 : SAMP2 o OBJ , :F1: SAMP 3. OB J & 
**T0 :F1: SAMPLE & 
**PRINT ( :F1: SAMPLE. LST) SYMBOLS LINES PUBLICS IXREF 

INPUT MODULES INCLUDED 
:F1: SAMPl, OBJ (SAMPLE) 
:F1: SAMP 2. OB J (CONSOLE_IO) 
:F1: SAMPS. OBJ (NUM_CONVERSION) 

LINK MAP FOR : Fl : SAMPLE (SAMPLE) 



TYPE 


BASE 


LENGTH 


RELOCATION 


SEGMENT NAME 














REG 


•0000H 


0008H 




"REG BANK 0" 


DATA 


0008H 


0008H 


ABSOLUTE 




DATA 


0010H 


000CH 


UNIT 


DATA_AREA 


CODE 


0000H 


005AH 


ABSOLUTE 




CODE 


005AH 


0056H 


UNIT 


CONSTANT AREA 


CODE 


00B0H 


004BH 


UNIT 


NUM ROUTINES 


CODE 


00FBH 


0044H 


UNIT 


10 ROUTINES 



SYMBOL TABLE FOR : Fl : SAMPLE (SAMPLE ) 
VALUE TYPE NAME 





MODULE 


SAMPLE 


C:005AH 


SEGMENT 


CONSTANT_AREA 


D:0010H 


SEGMENT 


DATA AREA 


C:0075H 


SYMBOL 


NUMl MSG 


D:0010H 


SYMBOL 


NUMl 


C:008CH 


SYMBOL 


NUM2_MSG 


D:0014H 


SYMBOL 


NUM2 


D:0098H 


SYMBOL 


SCON 


D:0008H 


SYMBOL 


STACK 


C:000BH 


SYMBOL 


START 


C:00A4H 


SYMBOL 


SUM MSG 


D:0018H 


SYMBOL 


SUM 


D:008DH 


SYMBOL 


THl 


D:0089H 


SYMBOL 


TMOD 


B:0088H„6 


SYMBOL 


TRl 


C:005AH 


SYMBOL 


TYPO MSG 




ENDMOD 


SAMPLE 




MODULE 


CONSOLE 10 


D: 00E0H 


SYMBOL 


ACC 


D:0000H 


SYMBOL 


AR0 


N: 000DH 


SYMBOL 


CR 


C:0110H 


SYMBOL 


EXIT 


C:0137H 


SYMBOL 


GET CHAR 



ISIS-II RL51 PAGE 

C:0125H SYMBOL GET_LOOP 

C:0121H PUBLIC GET_NUM 

C:0132H SYMBOL GO_ON 

C:00FBH SEGMENT IO_ROUTINES 

N:000AH SYMBOL LF 

CS0119H SYMBOL PUT CHAR 



Figure 5-4, RL51 Output File 
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C:00FBH 


PUBLIC 


PUT CRLF 


C:011iH 


PUBLIC 


PUT DATA STR 


Co0106H 


PUBLIC 


PUT STRING 


B:0098H 


SYMBOL 


RI 


D:0099H 


SYMBOL 


SBUF 


B:0098H,1 


SYMBOL 


TI 




ENDMOD 


CONSOLE 10 



MODULE NUM_CONVERSION 

D:00E0H SYMBOL ACC 

D:000iH SYMBOL ARl 

C:00B0H PUBLIC ASCBIN 

D:00F0H SYMBOL B 

CS00D8H PUBLIC BINASC 

C:00E2H SYMBOL G0_0N2 

N:002DH SYMBOL MINUS 

C:00B0H SEGMENT NUM_ROUTINES 

N:002BH SYMBOL PLUS 

C;00D5H SYMBOL POS 

B:00E0Ho7 SYMBOL SIGN 

N:0030H SYMBOL ZERO 

ENDMOD NUM_CONVERSION 

ISIS-II RL51 

INTER-MODULE CROSS-REFERENCE LISTING 

NAME USAGE MODULE NAMES 



PAGE 



ASCBIN. . . . 


CODE 


BINASC. . . , 


CODE 


GET NUM . . . 


CODE 


PUT CRLF, , , 


CODE 


PUT DATA STR. 


CODE 


PUT STRING, , 


CODE 



NUM_CONVERSION SAMPLE 
NUM_CONVERS ION SAMPLE 
CONSOLE_IO SAMPLE 
COWSOLE_IO SAMPLE 
CONSOLE_IO SAMPLE 
CONSOLE 10 SAMPLE 



Figure 5-4. RL51 Output File (Cont^d.) 



Using the Locating Controls 

The second example shows how to use the PRECEDE control to specify an order for 
data segments, in this case because the RL5 1 algorithm for locating segments results 
in a segment being left out. 

The program is named TESTOl. After assembly, the listing of TESTOl.OBJ is as 
shown in figure 5-5. The program's code sequence is irrelevant to the example. The 
two DATA segments, SEGl and SEG2, and the BIT segment, BIT3, are the points 
of interest for this example. 

SEGl is 21H bytes long; SEG2, 50H bytes long; SEG3, one bit long. The assembler 
listing also shows working register bank 0(8 bytes long, absolutely located at addresses 
OOH through 07H). 

All these segments are to be located in the on-chip data RAM of an 8051. For the 
8051, the directly-addressable on-chip data RAM is 80H bytes long (addresses OOH 
through 7FH); addresses 20H through 2FH are bit-addressable. The working regis- 
ters may occupy the first 20H bytes of the space. To see what RL5 1 does with this 
program, enter the command 

RL5 1 s F 1 I TESTO 1 , OBJ 
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MCS®.51 



MCS-51 MACRO ASSEMBLER 



TEST01 



ISIS-II MCS-51 MACRO ASSEMBLER V2 . 

OBJECT MODULE PLACED IN : Fl s TEST01 o OBJ 

ASSEMBLER INVOKED BY l iFlthSMSl 2 Fls TEST01 . SRC PRINT {iCOl] 

**OBJECT ( sFllTEST01oOBJ) 



LOC OBJ 



LINE SOURCE 

1 } This test shows the use of the 

2 ; PRECEDE locating control. 

3 ; One bit causes failure of the 

4 I RL51 allocation algorithm, 

5 ; but the PRECEDE control fixes it. 

6 } 

7 NAME test01 



0000 434F4445 
0004 20495320 
0008 49525245 
000C 4C455641 
0010 4E54 



0000 



0000 



0000 



9 
10 
11 
12 
13 
14 
15 
16 
17 
18 



19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 



prog 
segl 
seg2 
seg3 



SEGMENT 
SEGMENT 
SEGMENT 
SEGMENT 

RSEG 

Code segment. 

DB 



CODE 
DATA 
DATA 
BIT 

prog 



'CODE IS IRRELEVANT' 



RSEG 


segl 


DS 


021H 


RSEG 


seg2 


DS 


050H 


RSEG 


seg3 


DBIT 


001H 



END 



Figure 5-5. TESTOl Assembly Listing File 



The RL51 listing file is shown in figure 5-6. ERROR 107 informs us that the locate 
attempt for SEGl would overflow the data space; SEGl was ignored (not located) 
for this reason. The link map shows the following assignments for the remaining 
segments: 



Addresses 

OOH - 07H 
08H- IFH 

20H 

20H.1 -20H.7 

21H-71H 



Segment 

Register Bank 

GAP 

SEG3 (one bit at bit location 0) 

GAP 

SEG2 (50H bytes) 



After these segments have been located, there is not enough room for SEGl (21H 
bytes). However, there would be enough room if SEGl were located before the BIT 
segment. To obtain this result, the command is 

RL51 1FI1TESTOI.OBJ PRECEDECSEG1) 
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ISIS-II RL51 

ISIS-II MCS-51 RELOCATOR AND LINKER, V2 , , INVOKED BYs 
RL51 ;FlsTEST01,OBJ 



INPUT MODULES INCLUDED 
sFl:TEST01.OBJ(TEST01) 



LINK MAP FOR : Fl s TEST01 (TEST01 ) 



TYPE BASE 



LENGTH RELOCATION SEGMENT NAME 



REG 
BIT 
DATA 
CODE 



0000H 
0008H 
002 0H 
0020H, 
0021H 

0000H 



0008H 

0018H 

0000H= 

0000H, 

0050H 

0012H 



UNIT 



UNIT 



UNIT 



"REG BANK 0" 

•k-k'k Q^p -k-k^ 
SEG3 

** * GAP ** * 
SEG2 

PROG 



IGNORED SEGMENTS 
SEGl 

- ERROR 107s ADDRESS SPACE OVERFLOW 
SPACE; DATA 
SEGMENT: SEGl 



Figure 5-6. RL51 Listing File Without PRECEDE 



The RL51 listing file for this example is shown in figure 5-7. The PRECEDE control 
caused the link mapping to be as follows: 



Addresses 

OOH - 07H 
08H - 28H 
29H 

29H.1 -29H.7 
2AH - 7AH 



Segment 

Register Bank 

SEGl (21H bytes) 

SEG3 (one bit at bit location 0) 

GAP 

SEG2 (50H bytes) 



Refer to Chapter 2 for details on RLSl's allocating algorithm. 
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ISIS-II RL51 



ISIS-II MCS-51 RELOCATOR AND LINKER, X021, INVOKED BY: 
RL51 iFl: TEST01,OBJ PRECEDE (SEGl) 



INPUT MODULES INCLUDED 
:Fl:TEST01oOBJ (TEST01) 



LINK MAP FOR : Fl : TEST0i (TEST01 ) 



TYPE 


BASE 


LENGTH 


RELOCATION 


SEGMENT NAM 


REG 


0000H 


0008H 




"REG BANK 


DATA 


0008H 


0021H 


UNIT 


SEGl 


BIT 


0029H 


0000H,1 


UNIT 


SEG3 




0029H.1 


0000H.7 




■k-k-k G^p *** 


DATA 


002AH 


0050H 


UNIT 


SEG2 


CODE 


0000H 


0012H 


UNIT 


PROG 



Figure 5-7. RL51 Listing File with PRECEDE 



Using RL51 with PL/M-51 Modules 

The third example shows how to use RL51 with object modules produced by 
PL/M-51. The example shows the use of PLM51.LIB and demonstrates PL/M-51 
generated segments and the PL/M-51 to ASM51 linkage. 

The entire application introduces a way to halt ICE-51 at run time. The procedure 
CHECK_EQUAL in the PL/M-51 module CHK_EQ checks if an arithmetic 
expression is true. If yes, it calls the HALT_ICE assembler routine, which causes 
ICE51 to stop the program that is currently running. The code of the program is 
irrelevant; the example merely intends to show the program development process. 

The PLM51 main module CHK_EQ is compiled by 

PLM51 iF1iCHKEQ,P51 DEBUG PWC90) 

The output of the compilation is shown in figure 5-8. 

The ASM51 module HLTICE is assembled by 

ASM51 iF1s HLTICE, A5 1 DEBUG PWC90) 

The output of the compilation is shown in figure 5-9. 

RL5 1 is invoked by the following command: 

RL51 ;Fl!CHKEQ.0BJ,;F1sHLTICE.0BJ,PLM51.LIB IXREF PHC72) 

RL5 1 links the two pre-translated input modules, along with the mandatory library 
PLM51.LIB. PLM51.LIB must be linked whenever a PL/M-51 module participates 
in the linkage. The result of the linkage is shown in figure 5-10. 
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PL/M-51 COMPILER 



ICE51 - Check/Halt == 



PAGE 



ISIS-II PL/M-51 V1»0 

COMPILER INVOKED BY: pim51 : f 1: cnkeq.p51 debug pw(90) 



1 
2 
3 
5 
6 

7 
9 

10 

11 
12 



1 
1 
2 
1 
2 

2 
1 



$title (•== ICE51 - Check/Halt == ' ) 

y* ************************** *******^***^^^*^/ 

/* CHeck_equal: */ 

/* Check if comparison yields the */ 

/* expected result. If not, call */ 

/* assemiDler routine to return to ICE, */ 

/************************* *********^***^**^*/ 

chk_eq: 
DO; 

hal t_ice: 

PROCEDURE (vail, val2, eq_switch) EXTERNAL; 

DECLARE (vail, val2) WORD,- eq_swi tch BIT; END; 

check_equal : 

PROCEDURE (vail, val2, eq_switch) PUBLIC; 
DECLARE 

(vail, val2) WORD, 
eq_switch BIT; 

IF ((vail <> val2) <> eq_switch) 

THEN CALL nalt_ice (vail, val2, eq_switch); 
END check_equal; 

/* dummy main program */ 

DECLARE 

pi WORD CONSTANT (3) , 
Si WORD; 

CALL check_equal (pi*si , 27/si , 1); 

END chk eq; 



MODULE INFORMATIONS 
CODE SIZE 
CONSTANT SIZE 
DIRECT VARIABLE SIZE 
INDIRECT VARIABLE SIZE 
BIT SIZE 

BIT-ADDRESSABLE SIZE 
AUXILIARY VARIABLE SIZE 
MAXIMUM STACK SIZE 
REGISTER-BANK (S) USED: 
34 LINES READ 
PROGRAM ERROR (S) 

END OF PL/M-51 COMPILATION 



(STATIC+OVERLAYABLE) 



0057H 



87D 



0002H 


2D 




02H+04H 


2D + 


4D 


00H+00H 


0D + 


0D 


00H+01H 


0D+ 


ID 


00H+00H 


0D + 


0D 


0000H 


0D 




0006H 


6D 





Figure 5-8. PL/M-51 Listing File of CHK EQ 
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MCS®»51 



MCS-51 MACRO ASSEMBLER ' = = ICE51 - Halt == ' 

ISIS-II MCS-51 MACRO ASSEMBLER V2 , 

OBJECT MODULE PLACED IN : Fl : HLTICE« OBJ 

ASSEMBLER INVOKED BY: asmSi i f Is hi tice «a51 deoug pw(90) 



PAGE 



LOC OBJ 



LINE 



SOURCE 



0000 

0000 
0002 



0000 AC00 
0002 AD00 
0004 AE00 
0006 AF00 
0008 A200 

000A A5 
000B 00 
000C 00 
000D 00 
000E 22 



9 
10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 
40 
41 



$title ('== ICE51 - Halt ==') 
******* *******^******* *********************** 

* Halt_lce: * 

* Store word parameters in R45, R67, * 

* Bit in C and execute A5 instruction * 

* to return to ICE. * 
********************************************* ■ 

NAME halt_ice 

PUBLIC halt_ice, ?nal t_ice?Di t , ?hal t_ice?byte 
bits SEGMENT BIT 
bytes SEGMENT DATA 
prog SEGMENT CODE 



RSEG 


bits 


?halt ice?bits 


bit pa r : 




DBIT 


1 


RSEG 


bytes 


?halt icePbyte-. 


first pars 




DS 2 




second pars 




DS 2 




1 

RSEG 


prog 


halt ices 




MOV 


R4^first par 


MOV 


R5, first par + 1 


MOV 


R6, second par 


MOV 


R7rSecond par+1 


MOV 


C , b i t pa r 


DB 


0A5H 


NOP 




NOP 




NOP 




RET 





I move 1st par to place 

; move 2nd par to place 

} move bit par to place 

', illegal op-code, 

; Will stop ICE-51 if 

} you type "GO TIL OPC IS A5" 

} you can continue after stop 



END 



MCS-51 MACRO ASSEMBLER 
SYMBOL TABLE LISTING 



'== ICE51 



Halt == 



PAGE 



NAME 



TYPE 



VALUE 



ATTRIBUTES 



?HALT_ICE?BITo 
?HALT_ICE?BYTE 
BIT_PARo . 
BITS o o . 
BYTES, o o 
FIRST_PAR. 
HALT_ICE . 
PROG o o . 
SECOND PAR 



B ADDR 
D ADDR 
B ADDR 
B SEG 
SEG 
ADDR 
ADDR 
SEG 
ADDR 



0000H.0 

0000H 

0000H,0 

0001H 

0004H 

0000H 

0000H 

000FH 

0002H 



R 



PUB 
PUB 



PUB 



SEG=BITS 

SEG=BYTES 

SEG=BITS 

REL=UNIT 

REL=UNIT 

SEG=BYTES 

SEG=PROG 

REL=UNIT 

SEG=BYTES 



REGISTER BANK(S) USEDs 0, TARGET MACHINE (S)s 8051 
ASSEMBLY COMPLETE, NO ERRORS FOUND 



Figure 5-9. ASM51 Listing File of HLTICE 
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I IS-II RL51 



PAGE 



ISIS-II MCS-51 RELOCATOR AND LINKER, V2o0, INVOKED BYl 
RL51 :FlsCHKEQoOBJ, sFl:HLTICE.0BJ,PLM51»LIB IXREF PW(72) 



INPUT MODULES INCLUDED 
lFlsCHKEQ.OBJ(CHK_EQ) 
; Fl I HLT ICE o OBJ (HALT_ICE) 
sF0:PLM51oLIB(?P0034) 
iF0:PLM51,LIB(?P003 8) 
sF0 2PLM51»LIB(?PIV0R) 



LINK MAP FOR : Fl I CHKEQ (CHK EQ) 



TYPE 


BASE 


LENGTH 


RELOCATION 


SEGMENT NAME 














REG 


0000H 


0008H 




"REG BANK 0" 


DATA 


0008H 


0004H 


UNIT 


BYTES 


DATA 


000CH 


0004H 


UNIT 


?CHK EQ?DT?0 


DATA 


0010H 


0002H 


UNIT 


?CHK EQ?DT 




0012H 


000EH 




*** GAP *** 


BIT 


0020H 


0000H,1 


UNIT 


?CHK EQ?BI?0 


BIT 


0020H«1 


0000H«1 


UNIT 


BITS 




0020Ho2 


0000H«6 




*** GAP *** 


I DATA 


0021H 


0001H 


UNIT 


? STACK 


CODE 


0000H 


0003H 


ABSOLUTE 




CODE 


0003H 


0057H 


INBLOCK 


?CHK EQ?PR 


CODE 


005AH 


0016H 


UNIT 


7P0038S 


CODE 


0070H 


000FH 


UNIT 


PROG 


CODE 


007FH 


000CH 


UNIT 


?P0034S 


CODE 


008BH 


0009H 


UNIT 


7PIV0RS 


CODE 


0094H 


0002H 


UNIT 


?CHK EQ7C0 



SYMBOL TABLE FOR s Fls CHKEQ (CHK_EQ) 

VALUE TYPE NAME 

MODULE CHK_EQ 

CS0003H PUBLIC CHECK_EQUAL 

CI0033H SYMBOL CHK_EQ 

■ PROC CHECK_EQUAL 

DS000CH SYMBOL VALl 

DS000EH SYMBOL VAL2 

BS0020H SYMBOL EQ_SWITCH 

ENDPROC CHECK_EQUAL 

CS0094H SYMBOL PI 

DS0010H SYMBOL SI 

CI0033H LINE# 1 

CI0003H LINE# 5 

CS0003H LINE# 7 

CS001FH LINE# 8 

CI0032H LINE# 9 



Figure 5-10 . RL51 Listing File of CHK_EQ 
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RL51 






CI0033H 




LINE# 


11 


CI005AH 




LINE# 


12 






ENDMOD 


CHK_EQ 






MODULE 


HALT ICE 


BI0020H. 


,1 


PUBLIC 


?HALT ICE7BIT 


DS0008H 




PUBLIC 


7HALT ICE7BYTE 


BS0020H. 


,1 


SYMBOL 


BIT PAR 


BS0020H. 


,1 


SEGMENT 


BITS 


DI0008H 




SEGMENT 


BYTES 


DI0008H 




SYMBOL 


FIRST PAR 


C:0070H 




PUBLIC 


HALT ICE 


CS0070H 




SEGMENT 


PROG 


DI000AH 




SYMBOL 


SECOND PAR 






ENDMOD 


HALT ICE 



PAGE 



ISIS-II R L 5 1 



PAGE 



INTER-MODULE CROSS-REFERENCE LISTING 



NAME USAGE 



MODULE NAMES 



?CHECK_EQUAL?BIT . BIT? 

?CHECK_EQUAL?BYTE» DATA| 

?HALT_ICE?BIT. . . BIT| 

?HALT_ICE?BYTE . . DATA| 

7P0034 CODE; 

7P0038 CODEi 

7PIH0R CODEi 

7PIV0R CODEl 

7PSW0R . o « » o . NUMBi 

CHECK_EQUAL« . . . CODE | 

HALT ICE CODEl 



CHK_EQ 

CHK_EQ 

HALT_ICE CHK_EQ 

HALT_ICE CHK_EQ 

7P0034 CHK EQ 



7P0038 
CHK_EQ 
7PIV0R 
CHK_EQ 
CHK_EQ 
HALT ICE 



CHK_EQ 
7PIV0R 
CHK_EQ 
7PIV0R 

CHK EQ 



Figure 5»10 . RL51 Listing File of CHK_EQ (ContM , 



The result of a linkage process that includes PL/M-51 modules deserves an expla- 
nation. The following paragraphs describe the modules, segments, and symbols that 
appear in the output listing of such a linkage. The explanation refers to the actual 
example (figure 5-10). 

In addition to the two input modules CHK_EQ and HALT_ICE, RL51 pulled some 
modules from PLM51. LIB. The two modules 7P0034 and 7P0038 contain common 
PL/M-51 run-time routines and were pulled to resolve calls to those routines in the 
CHK_EQ module. The module 7PIV0R contains the initialization routine (set the 
stack pointer, set PSW), and is pulled whenever a linkage process encounters a main 
module written in PL/M-51. 

The segments BYTES, BITS, and PROG are the user segments as defined in the 
ASM51 HALT_ICE module. The code segments 7P0034S, 7P0038S and 7PIV0RS 
are the code segments of the previously explained run-time routines. 
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All segments whose names are of the form ?CHK_EQ? any are segments generated 
by PL/M-51 as result of compiling module CHK_EQ. The prefix ?CHK_EQ? 
indicates that the segment belongs to the CHK_EQ module. The suffix indicates the 
segment type; e.g, PR stands for the PRogram CODE segment, CO for the COnstant 
CODE segment, DT for DATA segment, and BI for BIT segment. 

On-chip segment names may be followed by a register bank number (0-3). This 
number indicates the register bank that must be in effect while data in this segment 
is accessed. 

The ? STACK segment was discussed before. Note that this segment is not supplied 
by the user, but is pulled automatically from PLM51.LIB because the main module 
is written in PL/M-51. The absolute segment at 0000H-0002H contains the reset 
vector, which consists of a JUMP to the initialization routine contained in the 
7PIV0RS segment. 

Most of PL/M-51 -generated relocatable segments have the UNIT relocation type. A 
frequent exception is the program code segment (?CHK_EQ?PR), which is 
INBLOCK whenever a module is compiled under ROM (MEDIUM), which is the 
default used by the compiler. Another (less frequent) exception is the BITAD- 
DRESSABLE DATA segment generated when bit structures are declared within the 
PL/M-51 source program. 

User symbols appear in the symbol table and the IXREF report. Symbols whose 
names are equal to segments and modules defined previously represent entry points 
in the appropriate modules/segments pulled from PLM51.LIB (e.g., the symbol 
7P0034 is a code address in the module 7P0034). 

Symbols in the format ? procedure? BYTE or 1 procedurelBlT (e.g,, 
?HALT_ICE?BYTE) are DATA and BIT addresses used for passing parameters to 
the appropriate external procedures (as implied by the name). BYTE and WORD 
parameters are placed at DATA address starting at, for example, 
?HALT_ICE?BYTE. BIT parameters are placed at BIT address starting at 
?HALT_ICE?BIT (see also the PL/M-51 Users Guide about PL/M-51 linkage to 
ASM51). 
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CHAPTER 6 
LIB51 LIBRARIAN 



Introduction 

LIB51 is used to create and manipulate library files. Library files are specially 
formatted collections of object modules, any element of which may be retrieved during 
the linkage process in order to resolve program references to external names. 

LIB51 also allows you to alter the contents of these files by adding new modules or 
deleting old ones. 

LIBS 1 user interface is fully compatible with LIB (the ISIS-II Librarian for the 8080 
and 8085 environment). 



LIB51 Input 

Input to LIB51 consists of modules originally generated by one of the 8051 language 
translators. 



The Invocation Line 

The LIB51 program is called by the command 

L IBB 1 icry 

LIB51 identifies itself with a sign-on message, followed by an asterisk prompt, shown 
as follows 

ISIS-I! MCS-51 LIBRARIAN Vx.y 

where 

x.y is the version number. 

While in LIB51, you will receive the asterisk prompt after each command is completed. 
Following the asterisk prompt, you may enter any of the following LIB51 subcom- 
mands: 

ADD 

CREATE 

DELETE 

EXIT 

LIST 

The Command Line 

If the command line is longer than a line on your particular console (up to the 
maximum of 122 characters allowed), you may continue it on the next line by enter- 
ing an ampersand ( & ) as the last non-blank character on the line before executing 
the carriage return. LIB51 responds to this with a double asterisk prompt ( ** ) to 
let you know that it is ready for the continuation of the command line. 
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LIB51 uses a temporary file named LIB.TMP on the library file disk. If you 
have a file with this name, it will be destroyed. 



Error Messages 

Appendix D lists the error messages generated by LIB51. 

LIB51 Subcommands 

Each of the LIB51 subcommands is described on the following pages. The syntax and 
definition of each subcommand is given, along with an example of its use. 

ADD 

The ADD command adds modules to a specified library. 

Syntax 

ADD fllenamei imodname, .,o)][,.,,] TO library 

Definition 

This command inserts modules into the library. The modules may be elements of 
another library, or they may be in object files. 

filename is the name of the file containing at least one object module, modname is 
the name of a module within filename; modname may be specified only if filename is 
a library file. 

If modnames are given, only the specified modules within filename are copied into 
library; otherwise, all modules are copied. You may enter as many filenames or 
modnames as you wish, library is the name of an existing library file, to which the 
specified modules will be added. 

Example 
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CREATE 

The CREATE command creates a new empty library. 

Syntax 

CREATE filename 



Definition 

This command creates a new library file called filename. If another file exists with 
that name, an error message is generated and the user is prompted for a new 
subcommand. 



DELETE 

The DELETE command deletes modules from a specified library. 

Syntax 

DELETE library i modname , . o , ) 

Definition 

The DELETE subcommand permits you to remove modules for which you have no 
need, from the specified library. DELETE removes the module specified and updates 
the library directory, library is the library from which the deletion is to be made, and 
modname is the name of the module to be removed. You may specify, as many 
modnames as you wish. 



Example 



BEllir SCHreOL oi IS '^'fiTLJ^^'S',. VE^-lf ^, ^'' Sir J) <S € r ^ 
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LIST 

The LIST command shows the current content of a specified library(ies). 

Syntax 

LIST libraryi C modname ,...)] [,...] E T listfile 1 [PUBLICS] 

Definition 

The LIST command enables you to examine the contents of the specified library. A 
listing of the contents of the library may be printed; you can send this list to a file to 
be printed later or you may print the list directly, depending upon listfile. If listfile is 
omitted, the listing is sent to the console output. 

library is the library for which you need the list of modules, modname is the name of 
the module desired, listfile is a file or an output device on which the list of modules is 
to be printed, and PUBLICS optionally calls for a listing of the public symbols in 
each listed module. 

Example 

The following examples illustrate the use of the LIST subcommand: 



C^r/"^^^.'-w 



*[LSif §€(;^@@[LoC;^Ei)'(^iglI(^it^i'^ :^fil' IM^'^^efi^ - -'"^^ - -■.;'->'- --'^ a-. >ii^f%MA^^ 



See figure 6-1 for an example of the LIST output format. 



PRINTED_MATTER 

PUBL I SHER 

LIBRARY_OF_CONGRESS_NUMBER 
DICTIONAR I ES 

ABR IDGED 

UNABR IDGED 
ENCYCLOPEDI AS 

VOLUMES 

SETS 

PUBL I SHER 
MAPS 

STATE 

COUNTRY 

RELI EF 

GLOBES 




Figure 6-1 . LIST Command Output 
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EXIT 

The EXIT terminates the LIB51 program. 

Syntax 
EXIT 
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APPENDIX A 
SUMMARY OF RL51 CONTROLS 



Table of Basic Definitions 

Table A- 1 gives definitions of basic terms used in the command format summary. 
Table A-1 . Definitions of Common Terms 



Term 


Definition 


name 


Names can be from 1 to 40 characters long and must be composed 
of letters A - Z, digits - 9, or special characters (?, @, _). The 
first character must be a letter or a special character. 


module-name 


Same as name. 


segment-name 


Same as name. 


pathname 


A valid ISIS-II filename reference or device reference. See next 
two items for examples. 


filename 


A reference to a disk file. The format is 




[:fn:]rootlext] 




Examples: PR0G1, :F1:SAMPL1, TEST.HEX, 




:F2:SAMPLE.0BJ 


device 


A reference to a non-disk device. 
Examples: :LP:, :C0:, :T0: 


value 


A 16-bit unsigned integer. 




Examples: 1011 B, 304Q, 4096D (or just 4096), 0C300H 


address 


Same as value. 



RL51 Command Format Summary 

Here is a summary of the syntax of the RL51 invocation command. Refer to the 
Preface for an explanation of the command format notation. 

The RL5 1 command has the overall format 

C I fni ] R L 5 1 input-list i T output-file 1 i control-list] 

where 

n I = ; drive number 

input-list I = input-file i module-list] [,...] 
input-file := filename ; see table A-1 
module-list i = i module-name [,...]) 
module-name ; = ; see table A- 1 
output-file ;= filename] see table A-1 
control-list i = control » . . 
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(listing-control 
linking-control 
locating-control 
configuration-control 
overlay-control 
/ print 



listing-control 



print 



pathname 

pagewidth i = 

value I ^ 



{pagewidth I 
map I 

symbols > 
publics I 
lines I 

ixref / 

PRINT [ (pathname) ]| 
NOPR I NT 

; see table A-1 

PAGEWIDTH i value} 

see table A-1 



map I = 
symbols 
publics 
lines I = 



ixref 



MAP 
NOMAP 

SYMBOLS 
NOSYMBDLS 

PUBL I CS 
NOPUBL I CS 

LINES 
NOL I NES 

IXREF i selection-list] 
NO I XREF 



selection-list i = (selection-item 
selection-item ; 



3 } 



(generated \ 
libraries \ 



generated 



GENERATED 
NOGENERATED 



libraries 



I L I B 
I NOL 



BRAR I ES 
I BRAR I ES 



linking-control \ = 

debugsymbols 
debuglines i = 
debugpublics 

locating-controls i 



NAME C module-name Y 
debugsymbols 
debuglines 
debugpublics 

DEBUGSYMBOLS 
NQDEBUGS YMBOLS 

DEBUGL I NES 
NODEBUGL I NES 

I DEBUGPUBL I CS 
I NODEBUGPUBL I CS 

PRECEDE 

DATA 

B I T 

I DATA 

STACK 

XDATA 

CODE 



( segment i 



] ) 



segment i = segment-name i (address) 1 
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segment-name s= ; see table A- 1 
address i= ; see table A- 1 

configuration-control i = ramsize 

ramsize s= RAMSIZE {value} 

value : = ; see table A- 1 

overlay-control i- [JJoJepl^Y ^ ^ overlay-uniti ,,,.]} ] 
overlay-unit i = ov-module-name calls ov-module-name 
ov-module-name i 



"{ 



module-name | 
module-name i = ; see table A- 1 
calls I = > 



Tables of Listing^ Linking, Locating^ and 
OveriayingControis 

Tables A-2 through A-6 describe the RL51 controls. Table A-7 gives abbreviations 
for the controls. 



Notes On Locating Controls 

The following notes refer to table A-4. 

1. Bit addresses for non-BIT segments in the BIT control must be on byte bounda- 
ries; that is, they must be divisible by eight. (BIT-type segments can be aligned 
on bit boundaries.) 

The range of addresses for the IDATA control is dependent on the target machine. 
The 8051 has 128 bytes (addresses OOH — 7FH). See the RAMSIZE control in 
this context. 



2. 



The STACK control specifies which segments are to be allocated uppermost in 
the IDATA space. The memory accessed starts after the highest on-chip RAM 
address occupied by any previously allocated segment, and continues to the top 
of the IDATA space. 

NOTE 

This control has no other effect on any segments. 

The IDATA ? STACK segment, if it exists, is placed higher than segments 
that were mentioned in the STACK control. 

Table A-2 , Listing Controls 



Control 


Effect 


PRINT [(pathname)] 


Sends the listing file to the file or device specified by 
pathname. 


NOPRINT 


Suppresses the listing file; overrides any of the following 
listing controls. 


PAGEWIDTH (value) 


Specifies the maximum page width to be used. 


MAP 


Outputs memory map to link summary. 


NOMAP 


Suppresses memory map. 


SYMBOLS 


Outputs local symbols to symbol table. 


NOSYMBOLS 


Suppresses local symbols. 
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Table A»2, Listing Controls (Contact, 



Control 


Effect 


PUBLICS 

NOPUBLICS 

LINES 

NOLINES 

\XREf [{selection-list)] 

NOIXREF 


Outputs public symbols to symbol table. 

Suppresses public symbols. 

Outputs line numbers to symbol table (high-level language 
translators only). 

Suppresses line numbers. 

Appends intermodule cross-reference report to print file. 

Suppresses the intermodule cross-reference report. 



NOTE: The default for any control (except IXREF) is the positive form (PRINT, MAP, SYMBOLS, 
PUBLICS, and LINES). 

Table A-3 . Linking Controls 



Control 


Effect 


NAME (module-name) 


Specifies the name of the output module. If the NAME control is 
omitted, the output module name defaults to the name of the first 
input module processed. 


DEBUGSYMBOLS 


Copies local symbol information to output file. 


NODEBUGSYMBOLS 


Suppresses local symbols. 


DEBUGPUBLICS 


Copies public symbol information to output file. 


NODEBUGPUBLICS 


Suppresses public symbols. 


DEBUGLINES 


Copies line number information (high-level language translators 
only) to output file. 


NODEBUGLINES 


Suppresses line numbers. 



NOTE: For all linking controls except NAME, the default is the positive form (DEBUGSYMBOLS, 
DEBUGPUBLICS, and DEBUGLINES). 

Table A-4 , Locating Controls 



Control 


Address Space 


Address Range 
(Hex) 


Segment Types 
(and Attributes) 


PRECEDE 


Register banks and bit- 
addressable space in 
on-chip data RAM 


00H-2FH 


DATA (UNIT-aligned); 
IDATA 


BIT 


Bit-addressable space 
in on-chip data RAM 


OOH - 7FH 
(see note 1 ) 


BIT; DATA; IDATA 


DATA 


Directly-addressable 
on-chip data RAM 


OOH - 7FH 


DATA (UNIT-aligned); 
IDATA 


IDATA 


Indirectly-addressable 
on-chip data RAM 


OOH - OFFH 
(see note 2) 


IDATA 


STACK 


Same as IDATA (see 
note 3) 


Same as IDATA 


Same as IDATA 


XDATA 


External data RAM 


- OFFFFH 


XDATA 


CODE 


Code memory 


- OFFFFH 


CODE 





Table A-5 . Configuration Controls 


Control 


Effect 


RAMSIZE (value) 


Specifies the amount of on-chip RAM the object is aimed to. 
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Table A-6 . Overky Controls 



Control 


Effect 


OVERLAY (overlay-units) 
NOOVERLAY 


Overlays data segments, based on the information in the module 
declarations and in the overlay units. 

Suppresses the overlaying of data segments. 



Table A-7 , Abbreviations for Command Words 



Command Word 


Abbreviation 


BIT 


Bl 


CODE 


CO 


DATA 


DT 


DEBUGLINES 


DL 


DEBUGPUBLICS 


DP 


DEBUGSYMBOLS 


DS 


GENERATED 


GN 


IDATA 


ID 


IXREF 


IX 


LIBRARIES 


LB 


LINES 


LI 


MAP 


MA 


NAME 


NA 


NODEBUGLINES 


NODL 


NODEBUGPUBLICS 


NODP 


NODEBUGSYMBOLS 


NODS 


NOGENERATED 


NOGN 


NOIXREF 


NOIX 


NOLIBRARIES 


NOLB 


NOLINES 


NOLI 


NOMAP 


NOMA 


NOOVERLAY 


NOOL 


NOPRINT 


NOPR 


NOPUBLICS 


NOPL 


NOSYMBOLS 


NOSB 


OVERLAY 


OL 


PAGEWIDTH 


PW 


PRECEDE 


PC 


PRINT 


PR 


PUBLICS 


PL 


RAMSIZE 


RS 


STACK 


ST 


SYMBOLS 


ST 


TO 


TO 


XDATA 


XD 
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RL51 ERROR MESSAGES 



RL51 error messages describe warnings, errors, and fatal errors. A warning is a 
detected condition that may or may not be what the user desired; a warning does not 
terminate the Unk/locate operation. An error does not terminate operation, but 
probably results in an output module that cannot be used. A fatal error terminates 
operation of RL5 1 . 

This appendix Hsts the warning, error, and fatal error messages in that order. The 
text of each message is in UPPER CASE. A brief explanation of the probable cause 
for the error condition accompanies each error message. 



Warnings 

NARNING 1; UNRESOLVED EXTERNAL SYMBOL 
SYMBOL: external-name 

MODULE: file-nameimodule-name) 

The specified external symbol, requested in the specified module, has no matching 
public symbol in any of the input modules. 

WARNING 2; REFERENCE MADE TO UNRESOLVED EXTERNAL 

8 YM BOL: external-name 

MODULE: file-name(moclule-name) 

REFERENCE: code-address 

The specified unresolved external is referenced in the specified module at the specified 
code address. 

WARNING 3; ASSIGNED ADDRESS NOT COMPATIBLE WITH 

AL IGNMENT 
SEGMENT: segment-name 

The address specified for the segment in a locating control is not compatible with the 
segment's alignment. The segment is placed at the specified address, violating its 
alignment. 

WARNING 4; DATA SPACE MEMORY OVERLAP 
FROM: byte.bit address 

TO: byte.bit address 

The data space in the given range is occupied by two or more segments. 

WARNING 5; CODE SPACE MEMORY OVERLAP 
FROM: byte address 

TO: byte address 

The code space in a given range is occupied by two or more segments. 

WARNING 6; XDATA SPACE MEMORY OVERLAP 
FROM: byte address 

TO: byte address 

The xdata space in the given range is occupied by two or more segments. 
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WARNING li HODULE NAME NOT UNIQUE 
MODULE: file-name(module~name) 

The specified name was used as the module name for more than one module. The 
specified module is not processed. 

WARNING Bi MODULE NAME EXPLICITLY REQUESTED FROM 

ANOTHER FILE 
MODULE: file-name(module-name) 

The specified module was requested, explicitly, to be processed from another file that 
has not yet been processed. The specified module is not processed. 

WARNING Si EMPTY ABSOLUTE SEGMENT 
MODULE: file'name(module-name) 

The specified module contains an empty absolute segment. This segment is not 
allocated. The base address of this segment may be overlapped without any additional 
message. 



Errors 

ERROR 1011 SEGMENT COMBINATION ERROR 
SEGMENT: segment-name 

MODULE: file-name(module-name) 

The attributes of the specified partial segment, in the specified module, contradict 
those of previous (unspecified) occurrences of partial segments with the same name. 
The segment is ignored. 

ERROR 102i EXTERNALS ATTRIBUTE MISMATCH 
SYMBOL: external-name 

MODULE: file-name(module-name) 

The attributes of the specified external symbol, in the specified module, contradict 
those of previous (unspecified) occurrences of public symbol with the same name. 
The specified symbol is ignored. 

ERROR 103i EXTERNAL ATTRIBUTES DO NOT MATCH PUBLIC 
SYMBOL: symbol-name 

MODULE: file-name(module-name) 

The attributes of the specified external (public) symbol, in the specified module, 
contradict those of previous (unspecified) occurrences of public (external) symbol 
with the same name. The specified symbol is ignored. 

ERROR 104? MULTIPLE PUBLIC DEFINITIONS 
SYMBOL: symbol-name 

MODULE: file-name(module-name) 

The specified public symbol, in the specified module, has already been defined in a 
previously (unspecified) processed module. The specified symbol is ignored. 
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ERROR 10E? PUBLIC REFERS TO IGNORED SEGMENT 
SYMBOL: public-name 

SEGMENT: segment-name 

The specified public symbol is defined referencing the specified ignored segment. The 
specified public symbol is ignored. 

ERROR 10Bs SEGMENT OVERFLOW 
SEGMENT: segment-name 

The specified segment, after combination, is larger than the maximum segment size 
allowed for the segment according to its type or to the given locating control. The 
specified segment is ignored. 

ERROR 107s ADDRESS SPACE OVERFLOW 
SPACE: space-name 

SEGMENT: segment name 

RL51 was unable to allocate the specified relocatable segment, according to the 
segment relocation type, in the specified address space. The specified segment is 
ignored. 

ERROR 108: SEGMENT IN LOCATING CONTROL CANNOT BE 

ALLOCATED 
SEGMENT: segment name 

RL51 was unable to allocate the specified relocatable segment that appears in the 
locating control, according to the requirements imposed by the locating control and 
according to the segment relocation type. The specified segment is ignored. 

ERROR 109: EMPTY RELOCATABLE SEGMENT 
SEGMENT: segment-name 

The specified segment, after combination has zero size. The specified segment is 
ignored. 

ERROR 110: CANNOT F I ND SEGMENT 
SEGMENT: segment-name 

The specified segment name occurred in the command tail but is not the name of any 
segment defined within the input files. The specified segment is ignored. 

ERROR 111: SPECIFIED BIT ADDRESS NOT ON BYTE BOUNDARY 
SEGMENT: segment-name 

The specified segment was requested in a BIT locating control. The segment is not a 
BIT segment, and the requested address is not on byte boundary. The specified 
segment is ignored. 

ERROR 112: SEGMENT TYPE NOT LEGAL FOR COMMAND 
SEGMENT: segment-name 

The specified segment is not one of the types that are legal for the locating control 
for which it is specified. The specified segment is ignored. 

ERROR 113: RESERVED . 
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ERROR 114i SEGMENT DOES NOT FIT 
SEGMENT: segment-name, base, length 

The specified segment cannot be located at the base specified by the locating control. 
Starting at that base address there is insufficient memory for a segment of its length. 
The specified segment is ignored. 

ERROR USi INPAGE SEGMENT IS GREATER THAN 2SB BYTES 
SEGMENT: segment-name 

The specified INPAGE segment is greater than one page. The specified segment is 
ignored. 

ERROR II61 INBLOCK SEGMENT IS GREATER THAN 2047 BYTES 
SEGMENT: segment-name 

The specified INBLOCK segment is greater than one block. The specified segment 
is ignored. 

ERROR 117? BIT ADDRESSABLE SEGMENT IS GREATER THAN 

16 BYTES 
SEGMENT: segment-name 

The specified BIT-ADDRESSABLE segment is greater than the BIT space. The 
specified segment is ignored. 

ERROR 118s REFERENCE MADE TO ERRONEOUS EXTERNAL 

SYMBOL: external-name 

MODULE: file-name(module-name) 

REFERENCE: code-address 

The specified, ignored external symbol is referenced in the specified module at the 
specified code address. 

ERROR 119s REFERENCE MADE TO ERRONEOUS SEGMENT 

SEGMENT: segment-name 

MODULE: flle-name(module-name) 

REFERENCE: code-address 

A symbol, which is defined using the specified, but ignored, segment, is referenced in 
the specified module at the specified code address. 

ERROR 120s CONTENT BELONGS TO ERRONEOUS SEGMENT 
SEGMENT: segment-name 

MODULE: flle-name(module-name) 

A content record, which belongs to the specified, but ignored, segment, has been 
encountered. The content record is not relocated. 

ERROR 12 1s IMPROPER F I XUP 

MODULE: file-name(module-name) 

SEGMENT: segment-name 

OFFSET: pseg-offset 

An error occurred in the evaluation of a fixup. An example of this error is when the 
value of the fixup expression does not meet the requirements of the type of the 
referenced location. 
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ERROR 122; CANNOT FIND MODULE 
MODULE: file-name(module-name) 

The specified module name, which was expHcitly requested from the specified file (in 
the command tail), was not found in that file. 

ERROR 12 3; ABSOLUTE IDATA SEGMENT DOES NOT FIT 

MODULE: file'name(module-name) 

FROM: data-address 

TO: data-address 

The specified module contains an absolute IDATA segment that occupies non-existent 
internal RAM space in the target machine. The segment is ignored. Notice, however, 
that the module may contain erroneous references to this segment, which are not 
reported. 

ERROR 124; RESERVED 

ERROR 125; MORE ERRORS ENCOUNTERED, NOT REPORTED 

Non-fatal errors encountered henceforth will not be reported. 

ERROR 126: OVERLAY MODULE NOT FOUND 
MODULE: file-name(module-name) 

The specified module name explicitly mentioned in the overlay control was not found. 

ERROR 127: OVERLAY DATA ADDRESS SPACE OVERFLOW 
SPACE: on-chipRAM space 

RL-51 was unable to allocate an overlaid segment of the specified address space. Try 
to link with the NOOVERLAY control. 

Fatal Errors 

FATAL ERROR 201: INVALID COMMAND LINE SYNTAX 
partial command 

A syntax error was detected in the command. The command is repeated up to and 
including the point of error. 

FATAL ERROR 202: INVALID COMMAND LINE; TOKEN TOO LONG 
partial command 

The command line contains a token that is too long. The command is repeated up to 
and including the point of error. 

FATAL ERROR 203: EXPECTED ITEM MISSING 
partial command 

An expected item in the command line, such as an input file name or a file name 
following the TO is missing. The command is repeated up to and including the point 
of error. 

FATAL ERROR 204: INVALID KEY WORD 
partial command 

An invalid keyword was found in the command. The command is repeated up to and 
including the point of error. 
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FATAL ERROR 205s NUMERIC CONSTANT TOO LARGE 
partial command 

A numeric constant greater than OFFFFH was found in the command. The command 
is repeated up to and including the point of error. 

FATAL ERROR 206? INVALID CONSTANT 
partial command 

An illegally constructed context was found. A common example of this error is enter- 
ing a hexadecimal number with a letter first. The command is repeated up to and 
including the point of error. 

FATAL ERROR 207 s I NVAL I D NAME 
partial command 

An illegally constructed name was found. Names can be from 1 through 40 charac- 
ters long and must be composed of the letters A-Z, the digits 0-9, or special charac- 
ters ("?", "@", "_")• The first character must be a letter or a special character. The 
command is repeated up to and including the point of error. 

FATAL ERROR 208: INVALID FILE NAME 
partial command 

The file-name specified in the command is not a valid ISIS-II file name. The command 
is repeated up to and including the point or error. 



FATAL ERROR 209: FILE USED IN CONFLICTING CONTEXTS 
FILE: file-name 

The specified file is used in more than one context, for example, using the same file 
for both input and output. (This may be caused by specifying for the first input file 
a file that has no extension, and not specifying an output file.) 

FATAL ERROR 210: I/O ERROR, INPUT FILE; ISIS-II ERROR# 
FILE: file-name 

An ISIS-II I/O error was detected in accessing an input file. The text of the message 
includes a description of the specific I/O error that occurred. See the ISIS-II User's 
Guide for a list of possible I/O errors. 

FATAL ERROR 211: I/O ERROR, OUTPUT FILE; ISIS-II ERROR# 
FILE: file-name 

An ISIS-II I/O error was detected in accessing the output file. The text of the message 
includes a description of the specific I/O error that occurred. See the ISIS-II User's 
Guide for a list of possible I/O errors. 

FATAL ERROR 2 12: I/O ERROR, LISTING FILE; ISIS-II 

ERROR# 
FILE: file-name 

An ISIS-II I/O error was detected in accessing the listing file. The text of the message 
includes a description of the specific I/O error that occurred. See the ISIS-II User's 
Guide for a list of possible I/O errors. 
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FATAL ERROR 213s I/O ERROR, TEMPORARY FILE; ISIS-II 

ERROR# 
FILE: file-name 

An ISIS-II I/O error was detected in accessing a temporary file. The text of the 
message includes a description of the specific I/O error that occurred. See the 
ISIS-II User's Guide for a list of possible I/O errors. 

FATAL ERROR 214s INPUT PHASE ERROR 
MODULE: file-name(module-name) 

This error occurs when RL5 1 encounters different data during pass two than it read 
during pass one. 

FATAL ERROR 215s CHECK SUM ERROR 
MODULE: file-name(module-name) 

A bad check sum was detected in the input module. This indicates a bad input module 
or a read error. 

FATAL ERROR 216; INSUFFICIENT MEMORY 

The memory available for execution of RL5 1 has been used up. This is usually caused 
by too many external /public symbols or segments in the input files or by too many 
errors. 

FATAL ERROR 217s NO MODULE TO BE PROCESSED 

After scanning all the input files, no module was selected to be processed. This is 
usually caused by an empty input file(s) or incorrect module names in the input list. 

FATAL ERROR 218s NOT AN OBJECT FILE 
FILE: file-name 

The file named in the message, judging by its first byte of data, is not a valid object 
file. 

FATAL ERROR 219s NOT AN 8051 OBJECT FILE 
FILE: file-name 

The translator-ID field in the module header record indicates that the specified module 
is not an 8051 object module. 

FATAL ERROR 220s INVALID INPUT MODULE 
MODU LE: file-name(module-name) 

The specified input module was found to be invalid. Possible causes are incorrect 
record order, incorrect record type, illegal field, illegal relation between fields, or a 
missing required record. This error could be the result of a translator record. 



FATAL ERROR 221s M D U L E S P E C I F I E D MORE THAN ONCE 
partial command 

The input list in the invocation line contains the same module name more than once. 
The command is repeated up to and including the point of error. 
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FATAL ERROR 222; SEGMENT SPECIFIED MORE THAN ONCE 
partial command 

The locating controls in the invocation line contain the same segment name more 
than once. The command is repeated up to and including the point of error. 

FATAL ERROR 2Z3 i NOT A DISK FILE 
partial command 

The file specified in the input list or as an output file is not a valid ISIS-II disk file 
name. The command is repeated up to and including the point of error. 

FATAL ERROR 224s DUPLICATE KEYNORD 
partial command 

The same keyword appears in the command more than once. The command is repeated 
up to and including the point of error. 

FATAL ERROR 225s SEGMENT ADDRESSES ARE NOT IN 

ASCENDING ORDER 
partial command 

The addresses of the segments within one locating control are not in ascending order. 
The command is repeated up to and including the point of error. 

FATAL ERROR 226: SEGMENT ADDRESS INVALID FOR CONTROL 
partial command 

The address requested for a segment is not valid for the given locating control. The 
command is repeated up to and including the point of error. 

FATAL ERROR 227; PAGENIDTH PARAMETER OUT OF RANGE 
partial command 

The PAGEWIDTH parameter given is out of the acceptable range. 

FATAL ERROR 228; RAMSIZE PARAMETER OUT OF RANGE 
partial command 

The RAMSIZE parameter given is out of acceptable range. 



FATAL ERROR 229; I/O ERROR, OVERLAY FILE; 

ISIS-II ERROR* 
FILE: file-name 

An ISIS-II I/O error was detected in accessing an overlay file. The text of the message 
includes a description of the specific I/O error that occurred. See the ISIS-II User's 
Guide for a list of possible I/O errors. (This error occurs only if IXREF was requested. 
Its occurrence does not invalidate the output object file.) 

FATAL ERROR 230; INCOMPATIBLE OVERLAY VERSION 
FILE: file-name 

The overlay file, although loaded successfully by ISIS-II, has a version number that 
is not the one expected by RL51. The possible cause is that the RL51 program and 
the loaded overlay are not of the same version. (This error occurs only if IXREF or 
OVERLAY was requested. If only IXREF was requested, the output object file is 
valid.) 
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FATAL ERROR 231: TOO MANY IXREF ENTRIES 

The number of IXREF entries (entry is a pair consisting of modules and symbol 
reference) is too large to be processed. The IXREF listing step is not performed. The 
NOLIBRARIES and NOGENERATED controls may be used in order to decrease 
this number and overcome the error. (This error occurs only if IXREF was requested. 
Its occurrence does not invalidate the output object file.) 

FATAL ERROR 232: OVERLAY CONTROL CONFLICTS XREF 
SELECTOR ITEMS 

The overlay control should not appear with the IXREF selector items NOLIBRAR- 
IES or NOGENERATED. 

FATAL ERROR 233: ILLEGAL USE OF ^ IN OVERLAY 
CONTROL 

The use of * > * with the OVERLAY control is illegal. 

FATAL ERROR 240: INTERNAL PROCESS ERROR 

RL51 has detected that it has made a processing error. This error indicates a bug 
within RL51. 
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APPENDIX C 
LIB51 COMMAND SUMMARY 



The following is a summary of the commands used by the LIBS 1 librarian. 

Command Action 

CREATE Creates a new library file 

ADD Inserts new modules into a library 



DELETE 
LIST 

EXIT 



Removes modules from a library 
Lists the contents of a library 
Returns control to ISIS 
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APPENDIX D 
LIB51 ERROR MESSAGES 



All LIB51 error messages are non-fatal because LIB51 is an interactive program. 
The command that caused the error will be aborted, but LIB51 will not be interrupted. 



Command Errors 

Errors caused by improper command entry are followed by a partial copy of the 
incorrect command, with a number sign (#) in the vicinity of the error, as shown 
below; 

ERROR MESSAGE 
partial command^ 

The following are the LIB51 command error messages: 

INSUFF! I ENT MEMORY 

LIB51 cannot execute the command given because it requires more memory than is 
available in the Intellec system. 

INVALID MODULE NAME 

A module listed in the command is incorrectly specified. Module names must conform 
to the format given in Chapter 2. 

INVALID SYNTAX 

Check the command for one of the following: 

® Misspelled keywords 

® Ampersand followed by a non-blank character 

® ADD: TO filename not followed by a < cr > 

® DELETE: libname (modname) not followed by a < cr > 

® DELETE: modname not specified 

® CREATE: filename not followed by a < cr > 

® LIST: TO filename not followed by PUBLICS or a < cr > 

LEFT PARENTHESIS EXPECTED 

There is a missing left parenthesis in the command. 

RIGHT PARENTHESIS EXPECTED 

There is a missing right parenthesis in the command. 

MODULE NAME TOO LONG 

The specified module name exceeds 40 characters. 

"T.O" EXPECTED 
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The TO filename is omitted in the ADD command. 

UNRECOGNIZED COMMAND 

An illegal or misspelled command was entered. The only legal commands are ADD, 
CREATE, DELETE, LIST, and EXIT. 

File or Module Errors 

The following errors indicate that there is some problem with the file or module 
specified. There is no partial copy of the command given with these error messages. 

F I LE ALREADY EXISTS 

The file specified in the CREATE command already exists. Choose a new name for 
the library. 

filename, DUPLICATE SYMBOL IN INPUT 

You have attempted to add a file that contains a PUBLIC symbol already within the 
library. 

filename, NOT LIBRARY 

The specified file is not a library. 

filename C modname ) i NOT FOUND 

You have attempted to delete a module that does not exist. Check for misspelling of 
the filename or module name. 

modname-~~(\ TTEMPT TO ADD DUPLICATE MODULE 

The specified module name already appears within the library. 

symbol—^ LREADY IN LIBRARY 

You have attempted to add a module that contains a PUBLIC symbol that is already 
in the library. 

///ename, CHECKSUM ERROR (See ISIS-II error 208.) 

f//ename, B J E C T RECORD TOO SHORT (See ISIS-II error 217.) 

f//efiame, I LLEGAL RECORD FORMAT (See ISIS-II error 218.) 

LIB51 cannot process the specified file because it is not a legal object file. Possible 
cause is a file damage or translator error. 
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APPENDIX E 
HEXADECIMAL-DECIMAL CONVERSION TABLE 



Table E-1 is for hexadecimal to decimal and decimal to hexadecimal conversion. To 
find the decimal equivalent of a hexadecimal number, locate the hexadecimal number 
in the correct position and note the decimal equivalent. Add the decimal numbers. 

To find the hexadecimal equivalent of a decimal number, locate the next lower decimal 
number in the table and note the hexadecimal number and its position. Subtract the 
decimal number shown in the table from the starting number. Find the difference in 
the table. Continue this process until there is no difference. 

Table E-1 . Hexadecimal-Decimal Conversion Table 



Most Sfgnlficant Byte 


Least Significant Byte 


Digit 4 


Digit 3 


Digit 2 


Digit 1 


HEX 


DEC 


HEX 


DEC 


HEX 


DEC 


HEX 


DEC 



1 
2 
3 
4 
5 
6 
7 
3 
9 
A 
B 

D 
E 
F 



4 096 
8 192 
12 288 
16 384 
20 480 
24 576 
28 672 
32 768 
36 864 
40 960 
45 056 
49 152 
53 248 
57 344 
61 440 



1 
2 
3 
4 
5 
6 
7 
8 
9 
A 
B 
C 
D 
E 
F 




256 

512 

768 

1 024 

1 280 

1 536 

1 792 

2 048 
2 304 
2 560 

2 816 

3 072 
3 328 
3 548 
3 840 



1 
2 
3 
4 
5 
6 
7 
8 
9 
A 
B 
C 
D 
E 
F 




16 

32 

48 

64 

80 

96 

112 

128 

144 

160 

176 

192 

208 

224 

240 



1 
2 
3 
4 
5 
6 
7 
8 
9 
A 
B 
C 
D 
E 
F 



1 
2 
3 
4 
5 
6 
7 
8 
9 

10 
11 
12 
13 
14 
15 
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abbreviations, 3-12, A-5 
absolute object file, 4-5 
absolute object module, 1-3 
absolute segments, 2-1 
ADD, 6-2 
address, 3-2 
address spaces, 2-2, 2-4 
allocation, 3-7 
allocation process, 2-3 
assembler (ASMS 1), 1-3,5-1 

BIT, 2-2, 2-3, 3-9 
BITADDRESSABLE, 2-2 
BLOCK, 2-2 

CODE, 2-2, 2-3, 3-9 
command entry, 3-1 
command, invocation, 

see invocation command 
comments, 3-1 
configuration controls, 3-1 1 
console display, 4-1 
continuation lines, 3-1 
control-list, 3-2 
controls, 3-4 

see also linking controls, listing controls, 

locating controls 
CREATE, 6-3 

DATA, 2-2, 2-3, 3-9 
DEBUG control, 1-3, 3-4, 3-6 
debugging, 1-1 
DEBUGLINES, 3-5 
DEBUGPUBLICS, 3-5 
DEBUGSYMBOLS, 3-5 
DELETE, 6-3 

development process, 1-1, 1-2 
device, 3-2 

editor, text, 1-3 

error messages, 4-4, B-1, D-1 

EXIT, 6-5 

external references, 2-4 

filename, 3-2 

hexadecimal-decimal conversion, E-1 

ICE-51 in-circuit emulator, 1-3 
IDATA, 2-1 thru 2-3, 3-9 
in-circuit emulator, 

see ICE-5 1 in-circuit emulator 
INPAGE, 2-1 
input-list, 3-1, 3-2 
invocation command, 3-1, 6-1 

address, 3-2 

control-list, 3-2 

device, 3-2 

filename, 3-2 



input-list, 3-1, 3-2 
module-name, 3-2 
name, 3-2 
output-file, 3-2, 3-3 
pathname, 3-2 
segment-name, 3-2 
IXREF, 4-4, 4-5 

LIB51, 6-1 thru 6-5 
error messages, D-1, D-2 
LINES, 3-5, 3-6, 3-12 
linking controls, 3-8, A-3 

NAME, 3-8 
linking switches, 3-8 

DEBUGLINES, 3-8 

DEBUGPUBLICS, 3-8 

DEBUGSYMBOLS, 3-8 

NODEBUGLINES, 3-8 

NODEBUGPUBLICS, 3-8 

NODEBUGSYMBOLS, 3-8 
link summary, 3-4, 4-1 
LIST, 6-4 
listing controls, 3-4, A-3 

DEBUG control, 3-5 

link summary, 3-4 

listing file, 3-4 
listing file, 4-1 
listing switches, 3-6 

IXREF, 4-4, 4-5 

LINES, 3-5, 3-6 

MAP, 3-5, 3-6 

NOLINES, 3-6 

NOMAP, 3-6 

NOPUBLICS, 3-6 

NOSYMBOLS, 3-6 

PUBLICS, 3-5, 3-6 

SYMBOLS, 3-5, 3-6 
locating controls, 3-9, 3-10, 3-11, 5-9, A-4 

BIT, 3-9 

CODE, 3-9 

DATA, 3-9 

IDATA, 3-9 

PRECEDE, 3-9, 5-9 

STACK, 3-9 

XDATA, 3-9 

major functions, 2-1 
MAP, 3-5 
memory map, 3-4 
modifying, 1-1 
module, 1-2, 2-1 
modular programming, 1-1 
module-name, 3-2 

NAME, 3-8 
name, 3-2 

NODEBUGLINES, 3-6 
NODEBUGPUBLICS, 3-6 
NODEBUGSYMBOLS, 3-6 
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NOIXREF, 3-6, 4-4 
NOLINES, 3-5 
NOMAP, 3-5 
NOOVERLAY, 3-12 
NOPRINT, 3-4 
notation, A-1 
NOPUBLICS, 3-5 
NOSYMBOLS, 3-5 

output-file, 3-2, 3-3 
OVERLAY, 3-12 

PAGE, 2-2 

partial segments, 2-2 

pathname, 3-2 

PRECEDE, 2-3, 3-9, 5-9 

PRINT, 3-4 

program, 1-2 

program development, 1-1, 1-2 

PROM programmer, 1-1 

PUBLICS, 3-5 



RAMSIZE, 3-12 
relocatable segments, 2-1, 2-2 
relocation, 1-3, 2-1 
RL51, 1-3,2-1,2-2,3-1,5-1 

command format, A-2 

controls, 3-4, A-1 

error messages, B-1 thru B-9 
.2-2 



SDK-51, 1-3 
segment, 1-2, 2-1 
segment-name, 3-2 
segment type, absolute, 2-1 
segment type, relocatable, 2-1 
STACK, 2-3 
SYMBOLS, 3-5 
symbol table, 4-3 

UNIT, 2-2 
XDATA, 2-2, 2-3, 3-9 
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